CodeIgniter, руководство пользователя к версии 1.6.1


Класс Active Record

CodeIgniter использует модифицированную версию паттерна Active Record Database. Этот паттерн позволяет извлекать, вставлять и обновлять информацию базы данных с помощью написания минимального количества кода. В некоторых случаях для выполнения действия с базой данных достаточно одной или двух строк кода. CodeIgniter не требует наличия отдельного файла с классом, соответствующего каждой таблице базы данных. Вместо этого CodeIgniter предоставляет более простой интерфейс.

Помимо простоты, главная особенность использования функционала Active Record заключается в том, что он позволяет вам создавать приложения независимые от какой-то конкретной базы данных, поскольку синтаксис запросов генерируется адаптером соответствующей базы данных. Так же он позволяет делать запросы более безопасными за счет автоматического экранирования значений.

Примечание: Если вы собираетесь писать свои собственные запросы, то вы можете отключить этот класс в вашем конфигурационном файле, тем самым позволив родной библиотеке базы данных и адаптеру использовать меньше системных ресурсов.

 Выбор данных

Следующие функции позволяют создавать SQL операторы SELECT.

Примечание: Если вы используете PHP 5, то можете использовать метод сцепления данных для получения более компактной записи. Этот метод описан в конце страницы.

$this->db->get();

Выполняет запрос выбора данных и возвращает результат. Сама по себе может быть использована для выбора всех записей из таблицы:

$query = $this->db->get('mytable');

// Генерирует: SELECT * FROM mytable

Второй и третий параметры позволяют задавать количество извлекаемых записей и начальное смещение:

$query = $this->db->get('mytable', 10, 20);

// Генерирует: SELECT * FROM mytable LIMIT 20, 10 (для MySQL. В других базах данных синтаксис будет немного отличаться.)

Заметьте, что вышеприведенная функция связана с переменной $query, которая может быть использована для отображения результатов запроса:

$query = $this->db->get('mytable');

foreach ($query->result() as $row)
{
    echo $row->title;
}

За более подробной информацией относительно генерирования результатов обратитесь к странице функции результатов.

$this->db->get_where();

Идентична вышеприведенной функции за исключением того, что она позволяет с помощью второго параметра добавить к запросу оператор «where», не прибегая к использованию функции db->where():

$query = $this->db->get_where('mytable', array('id' => $id), $limit, $offset);

Более подробная информация о функции where приведена ниже.

Примечание: get_where() ранее была известна как getwhere().

$this->db->select();

Позволяет задать имена выбираемых полей в вашем SELECT запросе:

$this->db->select('title, content, date');

$query = $this->db->get('mytable');

// Генерирует: SELECT title, content, date FROM mytable

Примечание: Если вы выбираете все (*) поля таблицы, то вам нет необходимости использовать эту функцию. Когда она опущена, CodeIgniter полагает, что вы хотите выполнить SELECT *.

$this->db->select() принимает второй необязательный параметр. Если вы установите его в FALSE, то CodeIgniter не будет пытаться обезопасить имена полей или таблиц с помощью одинарных кавычек. Это удобно, если вам нужно создать вложенный оператор select.

$this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE);
$query = $this->db->get('mytable');

$this->db->select_max();

Записывает «SELECT MAX(field)» в ваш запрос. Вы также можете во втором необязательном параметре указать новое имя результирующего поля.

$this->db->select_max('age');
$query = $this->db->get('members');
// Генерирует: SELECT MAX(age) as age FROM members

$this->db->select_max('age', 'member_age');
$query = $this->db->get('members');
// Генерирует: SELECT MAX(age) as member_age FROM members

$this->db->select_min();

Записывает «SELECT MIN(field)» в ваш запрос. Так же как и в select_max(), вы можно задать второй необязательный параметр, для указания нового имени результирующего поля.

$this->db->select_min('age');
$query = $this->db->get('members');
// Генерирует: SELECT MIN(age) as age FROM members

$this->db->select_avg();

Записывает «SELECT AVG(field)» в ваш запрос. Так же как и в select_max(), вы можно задать второй необязательный параметр, для указания нового имени результирующего поля.

$this->db->select_avg('age');
$query = $this->db->get('members');
// Генерирует: SELECT AVG(age) as age FROM members

$this->db->select_sum();

Записывает «SELECT SUM(field)» в ваш запрос. Так же как и в select_max(), вы можно задать второй необязательный параметр, для указания нового имени результирующего поля.

$this->db->select_sum('age');
$query = $this->db->get('members');
// Генерирует: SELECT SUM(age) as age FROM members

$this->db->from();

Позволяет задать FROM часть вашего запроса:

$this->db->select('title, content, date');
$this->db->from('mytable');

$query = $this->db->get();

// Генерирует: SELECT title, content, date FROM mytable

Примечание: Как было показано ранее, FROM часть запроса можно задать и с помощью функции $this->db->get(), так что используйте любой метод, который вам больше нравится.

$this->db->join();

Позволяет задать JOIN часть вашего запроса:

$this->db->select('*');
$this->db->from('blogs');
$this->db->join('comments', 'comments.id = blogs.id');

$query = $this->db->get();

// Генерирует:
// SELECT * FROM blogs
// JOIN comments ON comments.id = blogs.id

Возможно несколько вызовов функции, если необходимо сделать несколько объединений в одном запросе.

Если же вам нужно что-то отличное от обычного JOIN, вы может сделать это посредством третьего параметра функции. Допустимые значения: left, right, outer, inner, left outer и right outer.

$this->db->join('comments', 'comments.id = blogs.id', 'left');

// Генерирует: LEFT JOIN comments ON comments.id = blogs.id

$this->db->where();

Эта функция позволяет задать оператор WHERE с помощью одного из четырех способов:

Примечание: Для получения более безопасных запросов, все значения переданные в эту функцию автоматически заключаются в одинарные кавычки.

  1. Простой метод ключ/значение: $this->db->where('name', $name);

    // Генерирует: WHERE name = 'Joe'

    Заметьте, что знак равенства добавляется автоматически.

    Если производится несколько вызовов функции, то их результаты связывается друг с другом с помощью AND:

    $this->db->where('name', $name);
    $this->db->where('title', $title);
    $this->db->where('status', $status);

    // WHERE name = 'Joe' AND title = 'boss' AND status = 'active'
  2. Более гибкий метод ключ/значение:

    Для задания собственного метода сравнения, вы можете включить необходимый оператор в первый параметр:

    $this->db->where('name !=', $name);
    $this->db->where('id <', $id);

    // Генерирует: WHERE name != 'Joe' AND id < 45
  3. Метод использования ассоциативного массива: $array = array('name' => $name, 'title' => $title, 'status' => $status);

    $this->db->where($array);

    // Генерирует: WHERE name = 'Joe' AND title = 'boss' AND status = 'active'

    Так же вы можете ипользовать собственные операторы сравнения:

    $array = array('name !=' => $name, 'id <' => $id, 'date >' => $date);

    $this->db->where($array);
  4. Обычная строка:

    Вы можете вручную написать свой собственный оператор:

    $where = "name='Joe' AND status='boss' OR status='active'";

    $this->db->where($where);

$this->db->where() допускает использование третьего необязательного параметра. Если вы установите его в FALSE, то CodeIgniter не будет пытаться обезопасить имена полей или таблиц с помощью одинарных кавычек.

$this->db->where('MATCH (field) AGAINST ("value")', NULL, FALSE);

$this->db->or_where();

Эта функция идентична предыдущей за тем исключением, что при нескольких вызовах, результаты объединяются с помощью OR:

$this->db->where('name !=', $name);
$this->db->or_where('id >', $id);

// Генерирует: WHERE name != 'Joe' OR id > 50

Примечание: or_where() ранее была известна как orwhere().

$this->db->where_in();

Генерирует SQL запрос WHERE field IN ('item', 'item') присоединяя его при необходимости с помощью AND

$names = array('Frank', 'Todd', 'James');
$this->db->where_in('username', $names);
// Генерирует: AND WHERE username IN ('Frank', 'Todd', 'James')

$this->db->or_where_in();

Генрирует SQL запрос WHERE field IN ('item', 'item') присоеденяя его при необходимости с помощью OR

$names = array('Frank', 'Todd', 'James');
$this->db->or_where_in('username', $names);
// Генерирует: OR WHERE username IN ('Frank', 'Todd', 'James')

$this->db->where_not_in();

Генрирует SQL запрос WHERE field NOT IN ('item', 'item') присоеденяя его при необходимости с помощью AND

$names = array('Frank', 'Todd', 'James');
$this->db->where_not_in('username', $names);
// Генерирует: AND WHERE username NOT IN ('Frank', 'Todd', 'James')

$this->db->or_where_not_in();

Генрирует SQL запрос WHERE field NOT IN ('item', 'item') присоеденяя его при необходимости с помощью OR

$names = array('Frank', 'Todd', 'James');
$this->db->or_where_not_in('username', $names);
// Генерирует: OR WHERE username NOT IN ('Frank', 'Todd', 'James')

$this->db->like();

Эта функция позволяет генерировать оператор LIKE, используемый при поиске данных.

Примечание: Все значения переданные в эту функцию автоматически заключаются в одинарные кавычки.

  1. Простой метод ключ/значение: $this->db->like('title', 'match');

    // Генерирует: WHERE title LIKE '%match%'

    Если вы производите несколько вызовов функции, то их результаты объединяются с помощью AND:

    $this->db->like('title', 'match');
    $this->db->like('body', 'match');

    // WHERE title LIKE '%match%' AND body LIKE '%match%
    Если вы хотите контроллировать расположение специального символа (%), то вы можете использовать третий необязательный параметр. Доступные значения: 'before', 'after' и 'both' (по-умолчанию). $this->db->like('title', 'match', 'before');
    // Генерирует: WHERE title LIKE '%match'

    $this->db->like('title', 'match', 'after');
    // Генерирует: WHERE title LIKE 'match%'

    $this->db->like('title', 'match', 'both');
    // Генерирует: WHERE title LIKE '%match%'
  2. Метод использования асоциативного массива: $array = array('title' => $match, 'page1' => $match, 'page2' => $match);

    $this->db->like($array);

    // WHERE title LIKE '%match%' AND page1 LIKE '%match%' AND page2 LIKE '%match%'

$this->db->or_like();

Эта функция идентична предыдущей за тем исключением, что при нескольких вызовах результаты объединяются с помощью OR:

$this->db->like('title', 'match');
$this->db->or_like('body', $match);

// WHERE title LIKE '%match%' OR body LIKE '%match%'

Примечание: or_like() ранее была известна как orlike().

$this->db->not_like();

Эта функция идентична like() за тем исключением, что она генерирует NOT LIKE оператор:

$this->db->not_like('title', 'match');

// WHERE title NOT LIKE '%match%

$this->db->or_not_like();

Эта функция идентична not_like() за тем исключением, что при нескольких вызовах результаты объединяются с помощью OR:

$this->db->like('title', 'match');
$this->db->or_not_like('body', 'match');

// WHERE title LIKE '%match% OR body NOT LIKE '%match%'

$this->db->group_by();

Позволяет задавать GROUP BY часть вашего запроса:

$this->db->group_by("title");

// Генерирует: GROUP BY title

Вы так же можете передать массив с несколькими значениями:

$this->db->group_by(array("title", "date"));

// Генерирует: GROUP BY title, date

Примечание: group_by() ранее была известна как groupby().

$this->db->distinct();

Добавляет ключевое слово «DISTINCT» в запрос

$this->db->distinct();
$this->db->get('table');

// Генерирует: SELECT DISTINCT * FROM table

$this->db->having();

Позволяет задавать HAVING часть запроса. Возможно 2 вида синтаксиса, с одним аргументом или с двумя:

$this->db->having('user_id = 45');
// Генерирует: HAVING user_id = 45

$this->db->having('user_id', 45);
// Генерирует: HAVING user_id = 45

Вы так же можете передать массив с несколькими значениями:

$this->db->having(array('title =' => 'My Title', 'id <' => $id));

// Генерирует: HAVING title = 'My Title', id < 45

Если вы используете базу данных, для которой CodeIgniter заключает запросы в одинарные кавычки, то вы можете отключить заключение содержания в одинарные кавычки, установив третий необязательный аргумент в FALSE.

$this->db->having('user_id', 45);
// Генерирует: HAVING `user_id` = 45 в некоторых базах данных, таких как MySQL
$this->db->having('user_id', 45, FALSE);
// Генерирует: HAVING user_id = 45

$this->db->or_having();

Идентична having(), только несколько операторов разделяются «OR».

$this->db->order_by();

Позволяет задавать оператор ORDER BY. Первый параметр содержит имя столбца по которому необходимо упорядочить результаты. Второй параметр позволяет задать направление упорядочивания. Возможные значения: asc, desc или random.

$this->db->order_by("title", "desc");

// Генерирует: ORDER BY title DESC

Вы так же можете передать первым параметром собственную сроку:

$this->db->order_by('title desc, name asc');

// Генерирует: ORDER BY title DESC, name ASC

Или вызвать функцию несколько раз, если необходимо упорядочить результаты по нескольким полям.

$this->db->order_by("title", "desc");
$this->db->order_by("name", "asc");

// Генерирует: ORDER BY title DESC, name ASC

Примечание: order_by() ранее была известна как orderby().

Примечание: Упорядочивание типа random не поддерживается Oracle или MSSQL драйверами. И по-умолчанию будет установленно в «ASC».

$this->db->limit();

Позволяет задать ограничение на количество строк возвращаемых в результате запроса:

$this->db->limit(10);

// Генерирует: LIMIT 10

Второй параметр позволяет задать смещение с которого будут отсчитываться выводимые результаты.

$this->db->limit(10, 20);

// Генерирует: LIMIT 20, 10 (в MySQL. Другие базы данных имеют немного другой синтаксис)

$this->db->count_all_results();

Позволяет определить количество строк в текущем запросе Active Record. Запросы будут содержать ограничения Active Record, такие как where(), or_where(), like(), or_like(), и т. д. Пример:

echo $this->db->count_all_results('my_table');
// Возвращает целое число, например 25

$this->db->like('title', 'match');
$this->db->from('my_table');
echo $this->db->count_all_results();
// Возвращает целое число, наприме 17

$this->db->count_all();

Позволяет определить количество строк в текущей таблице. Принимает имя таблицы в качестве первого параметра. Пример:

echo $this->db->count_all('my_table');

// Возвращает целое число, наприме 25
 

Вставка данных

$this->db->insert();

На основе предоставленных данных генерирут запрос вставки в выполняет его. Так же в функцию можно передать массив или объект. Вот пример использования массива:

$data = array(
               'title' => 'My title' ,
               'name' => 'My Name' ,
               'date' => 'My date'
            );

$this->db->insert('mytable', $data);

// Генерирует: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')

Первый параметр содержит имя таблицы, второй — ассоциативцый массив значений.

А вот пример использования объекта:

/*
    class Myclass {
        var $title = 'My Title';
        var $content = 'My Content';
        var $date = 'My Date';
    }
*/

$object = new Myclass;

$this->db->insert('mytable', $object);

// Генерирует: INSERT INTO mytable (title, content, date) VALUES ('My Title', 'My Content', 'My Date')

Первый параметр содержит имя таблицы, второй — объект.

Примечание: Для генерации более безопасных запросов все значения автоматически заключаются в одинарные кавычки.

$this->db->set();

Эта функция позволяет задавать значения для вставляемых (insert) или обновляемых (update) данных.

Она может использоваться вместо непосредственной передачи массива данных в функцию insert или update:

$this->db->set('name', $name);
$this->db->insert('mytable');

// Генерирует: INSERT INTO mytable (name) VALUES ('{$name}')

Если вы производите несколько вызовов функции, то метод их объединения будет определяться исходя из того, какой запрос вы производите — insert или update:

$this->db->set('name', $name);
$this->db->set('title', $title);
$this->db->set('status', $status);
$this->db->insert('mytable');

set() также позволяет задать третий необязательный параметр ($escape), который, будучи установленным в FALSE, предотвращает заключение данных в одинарные кавычки. Для иллюстрации различий, ниже показан результат вызова set() с третьим параметром и без него.

$this->db->set('field', 'field+1', FALSE);
$this->db->insert('mytable');
// получается INSERT INTO mytable (field) VALUES (field+1)

$this->db->set('field', 'field+1');
$this->db->insert('mytable');
// получатся INSERT INTO mytable (field) VALUES ('field+1')

Вы также можете передать в функцию ассоциативный массив:

$array = array('name' => $name, 'title' => $title, 'status' => $status);

$this->db->set($array);
$this->db->insert('mytable');

... или объект:

/*
    class Myclass {
        var $title = 'My Title';
        var $content = 'My Content';
        var $date = 'My Date';
    }
*/

$object = new Myclass;

$this->db->set($object);
$this->db->insert('mytable');
 

Обновление данных

$this->db->update();

На основании предоставленных данных генерирует и выполняет запрос обновления данных. Вы можете передать в функцию массив или объект. Вот пример использования массива:

$data = array(
               'title' => $title,
               'name' => $name,
               'date' => $date
            );

$this->db->where('id', $id);
$this->db->update('mytable', $data);

// Генерирует:
// UPDATE mytable
// SET title = '{$title}', name = '{$name}', date = '{$date}'
// WHERE id = $id

Или вы можете передать в функцию объект:

/*
    class Myclass {
        var $title = 'My Title';
        var $content = 'My Content';
        var $date = 'My Date';
    }
*/

$object = new Myclass;

$this->db->where('id', $id);
$this->db->update('mytable', $object);

// Produces:
// UPDATE mytable
// SET title = '{$title}', name = '{$name}', date = '{$date}'
// WHERE id = $id

Примечание: Для генерации более безопасных запросов все значения автоматически заключаются в одинарные кавычки.

Заметьте, вы можете использовать функцию $this->db->where(), для задания оператора WHERE. При желании вы можете передать эту информацию непосредственно в функцию update в виде строки:

$this->db->update('mytable', $data, "id = 4");

... или массива:

$this->db->update('mytable', $data, array('id' => $id));

Также вы можете использовать описанную выше функцию $this->db->set() для задания обновляемых полей.

 

Удаление данных

$this->db->delete();

Генерирует SQL запрос delete и выполняет его.

$this->db->delete('mytable', array('id' => $id));

// Генерирует:
// DELETE FROM mytable
// WHERE id = $id

Первый параметр — имя таблицы, второй — оператор where. Вы также можете использовать функции where() или or_where() вместо непосредственной передачи данных во второй параметр функции:

$this->db->where('id', $id);
$this->db->delete('mytable');

// Генерирует:
// DELETE FROM mytable
// WHERE id = $id

Если вы хотите удалить данные из более чем одной таблицы, то вы можете передать в функцию массив с именами таблиц.

$tables = array('table1', 'table2', 'table3');
$this->db->where('id', '5');
$this->db->delete($tables);

Если вы хотите удалить все данные из таблицы, то можете использовать функцию truncate() или empty_table().

$this->db->empty_table();

Генерирует SQL запрос delete и выполняет его. $this->db->empty_table('mytable');

// Генерирует
// DELETE FROM mytable

$this->db->truncate();

Генерирует SQL запрос truncate и выполняет его.

$this->db->from('mytable');
$this->db->truncate();
// or
$this->db->truncate('mytable');

// Генерирует:
// TRUNCATE mytable

Примечание: Если команда TRUNCATE не доступна, truncate() выполняется как «DELETE FROM table».

 Метод сцепления данных

Метод сцепления данных позволяет вам упростить соединение результатов нескольких функций. Рассмотрим следующий пример:

$this->db->select('title')->from('mytable')->where('id', $id)->limit(10, 20);

$query = $this->db->get();

Примечание: Метод сцепления данных работает только в PHP 5.

 

 Кэширование Active Record

Пока отсутствует «настоящее» кэширование, Active Record позволяет сохранять (или «кэшировать») определенные части ваших запросов, для последующего их использования. Обычно, когда завершается вызов Active Record, то вся хранящаяся информация сбрасывается для выполнения следующего вызова. Кэширование позволяет предотвратить это сбрасывание и сделать повторное использование информации более простым.

Кэшированные запросы кумулятивны. Если вы делаете 2 кэшированных вызова select() и 2 некэшированных вызова select(), то в результате получите 4 вызова select(). Доступны три функции кэширования:

$this->db->start_cache()

Эта функция должна быть вызванна для начала кэширования. Все Active Record запросы определенных типов (см. ниже поддерживаемые запросы) будут сохраненны для последующего использования.

$this->db->stop_cache()

Эта функция может быть вызванна для прекращения кэширования.

$this->db->flush_cache()

Эта функция удаляет все элементы из кэша Active Record.

Вот пример использования:

$this->db->start_cache();
$this->db->select('field1');
$this->db->stop_cache();
$this->db->get('tablename');
// В итоге:
// SELECT `field1` FROM (`tablename`)

$this->db->select('field2');
$this->db->get('tablename');
// В итоге:
// SELECT `field1`, `field2` FROM (`tablename`)

$this->db->flush_cache();

$this->db->select('field2');
$this->db->get('tablename');
// В итоге:
// SELECT `field2` FROM (`tablename`)

Примечание: Кэшироваться могут следующие поля: ‘select’, ‘from’, ‘join’, ‘where’, ‘like’, ‘groupby’, ‘having’, ‘orderby’, ‘set’