Подробности аутентификации в базе данных¶

Параметры: username и password

Некоторые адаптеры баз данных (такие как MySQL) требуют раздельной передачи имени пользователя (username) и пароля (password) в DSN строке. Эти параметры позволяют вам передать их. Типичная настройка соединения MySQL может выгялдеть так:

<?php
ORM::configure('mysql:host=localhost;dbname=my_database');
ORM::configure('username', 'database_user');
ORM::configure('password', 'top_secret');

Или вы можете соединить настройку соединения в одну строку, используя массив конфигурации:

<?php
ORM::configure(array(
    'connection_string' => 'mysql:host=localhost;dbname=my_database',
    'username' => 'database_user',
    'password' => 'top_secret'
));

Наборы результатов¶

Параметр: return_result_sets

Коллекция результатов данных может быть возвращена в качестве массива (по-умолчанию) или в виде результирующего набора. Смотрите документацию о find_result_set() для более подробной информации.

<?php
ORM::configure('return_result_sets', true); // возвращает результирующий набор

PDO Параметры драйвера¶

Параметр: driver_options

Некоторые адаптеры базы данных требуют (или позволяют использовать) массив параметров конфигурации для конкретного драйвера. Это позволяет вам передавать эти параметры через конструктор PDO. Для более подробной информации, смотрите документацию PDO. Например, чтобы заставить драйвер MySQL использовать кодировку UTF-8 для соединения:

<?php
ORM::configure('driver_options', array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8'));

PDO Режим ошибок¶

Параметр: error_mode

Можно использовать для установки параметра PDO::ATTR_ERRMODE у класса соединения с базой данных, используемой Idiorm. Должна быть передана одна из объявленных в классе констант PDO. Пример:

<?php
ORM::configure('error_mode', PDO::ERRMODE_WARNING);

Параметром по-умолчанию является PDO::ERRMODE_EXCEPTION. Для более подробной информации о доступных режимах ошибок, смотри документация PDO - присвоение атрибута.

PDO доступ к объекту¶

Если он когда-то потребуется, то объект PDO, используемый в Idiorm может быть получен напрямую через ORM::get_db(), или установлен напрямую через ORM::set_db(). Однако это редкое явление.

После того, как заявление было выполнено с помощью любых средств, таких, как ::save() или ::raw_execute(), испольуземый экземпляр PDOStatement может быть получен через ORM::get_last_statement(). Это может быть полезно для доступа к PDOStatement::errorCode(), если исключения в PDO отключены, или для доступа к методу PDOStatement::rowCount(), который возвращает различные результаты, относительно основной базы данных. Чтобы узнать больше, смотри PDOStatement документация.

Идентификатор символа кавычек¶

Параметр: identifier_quote_character

Устанавливает символ, используемый для идентификации кавычек (например имени таблицы, имени столбца). Если не задан, то будет определен автоматически в зависимости от драйвера базы данных, используемого в PDO.

ID столбца¶

По-умолчанию, ORM предполагает, что у всех ваших таблиц есть колонка первичного ключа(primary key)

с именем id. Есть два способа это переопределить: для всех таблиц в базе данных, или на основе каждой таблицы.

Параметр: id_column

Этот параметр используется для конфигурации имени столбца первичного ключа (primary key) всех таблиц. Если ваша ID-колонка имеет название primary_key, используйте:

<?php
ORM::configure('id_column', 'primary_key');

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

<?php
ORM::configure('id_column', array('pk_1', 'pk_2'));

Примечание: Если вы используете столбец с auto-increment в составном первичном ключе, то он должен быть объявлен первым в массиве.

Параметр: id_column_overrides

Этот параметр используется для указания имени столбца первичного ключа для каждой таблицы отдельно. Он принимает ассоциативный массив, описывающий название таблиц и имен столбцов. Например, если, имена ID-столбца включают имя таблицы, то вы можете использовать следующую настройку:

<?php
ORM::configure('id_column_overrides', array(
    'person' => 'person_id',
    'role' => 'role_id',
));

Как и параметр id_column, вы можеите указать составной первичный ключ, используя массив.

Limit clause style¶

Параметр: limit_clause_style

Вы можете установить стиль ограничения в конфигурации. Это делается для облегчения ограничений в стиле MS SQL, использующий синтаксис TOP.

Допустимыми значениями являются ORM::LIMIT_STYLE_TOP_N и ORM::LIMIT_STYLE_LIMIT.

Лог запросов¶

Параметр: logging

Idiorm может записывать в лог все вызываемые запросы. Для включения лога запросов, установите параметр logging на true (по-умолчанию он имеет значение false).

Когда лог запросов включен, вы можете использовать два статических метода для доступа к логу. ORM::get_last_query() возвращает самый последний вызванный запрос. ORM::get_query_log() возвращает массив всех вызванных запросов.

Logger запросов¶

Параметр: logger

Можно передать в этот параметр конфигурации callable, который будет вызываться для каждого запроса, вызываемого idiorm. В PHP callable зовется все, что может быть вызвано, как если бы это была функция. Чаще всего это будет представляться в виде анонимной функции.

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

<?php
ORM::configure('logger', function($log_string, $query_time) {
    echo $log_string . ' in ' . $query_time;
});

Кэширование запросов¶

Параметр: caching

Idiorm может кэшировать выполняемые запросы во время обращения. Для включения кэширования запросов, установите параметру caching значение true (по-умолчанию имеет значение false).

<?php
ORM::configure('caching', true);

Параметр: caching_auto_clear

По-умолчанию, кэш Idiorm никогда не очищается. Если вы хотите, чтобы он очищался после сохранения, установите параметр caching_auto_clear на значение true

<?php
ORM::configure('caching_auto_clear', true);

Когда включено кэширование запросов, Idiorm будет кэшировать результаты каждой выборки SELECT, которая была вызвана. Если Idiorm сталкивается с запросом, который уже был вызван, то он извлечет результаты прямо из кэша и не будет обращаться к базе данных.

<?php
$my_cache = array();
ORM::configure('cache_query_result', function ($cache_key, $value, $table_name, $connection_name) use (&$my_cache) {
    $my_cache[$cache_key] = $value;
});
ORM::configure('check_query_cache', function ($cache_key, $table_name, $connection_name) use (&$my_cache) {
    if(isset($my_cache[$cache_key])){
       return $my_cache[$cache_key];
    } else {
    return false;
    }
});
ORM::configure('clear_cache', function ($table_name, $connection_name) use (&$my_cache) {
     $my_cache = array();
});

ORM::configure('create_cache_key', function ($query, $parameters, $table_name, $connection_name) {
    $parameter_string = join(',', $parameters);
    $key = $query . ':' . $parameter_string;
    $my_key = 'my-prefix'.crc32($key);
    return $my_key;
});

Как результирующий набор¶

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

Итак, для примера, вместо этого:

<?php
$people = ORM::for_table('person')->find_many();
foreach ($people as $person) {
    $person->age = 50;
    $person->save();
}

Вы можете использовать это:

<?php
ORM::for_table('person')->find_result_set()
->set('age', 50)
->save();

Чтобы это сделать, замените любой вызов метода find_many() методом find_result_set().

Результирующий набор ведет себя так же, как и массив, так что вы можете использовать на нем count() и foreach как и с массивом.

<?php
foreach(ORM::for_table('person')->find_result_set() as $record) {
    echo $record->name;
}

<?php
echo count(ORM::for_table('person')->find_result_set());

Как ассоциативный массив¶

Так же вы можете найти множество записей в виде ассоциативного массива, вместо экземпляров Idiorm. Для этого замените любой вызов метода find_many() на метод find_array().

<?php
$females = ORM::for_table('person')->where('gender', 'female')->find_array();

Это полезно, если вам нужно преобразовать результат запроса в последовательную форму записи(сериализация массива) для JSON, и вам не нужно дополнительной возможности обновлять возвращаемые данные.

Предостережения¶

Только подмножество доступных условий, поддерживаемых SQL доступны при использовании Idiorm. Кроме того, все пункты WHERE будут соединены с использованием AND при выполнении запроса. Поддержка OR в пунктах WHERE в настоящее время отстутствует.

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

Некоторая поддержка более сложных условий и запросов реализована в методах where_raw и raw_query (смотрите ниже). Если вы поймете, что чаще нуждаетесь в в большем функционале, нежели содержит Idiorm, то возможно пришло время рассмотреть более полнофункциональный ORM.

Равенство: where, where_equal, where_not_equal¶

По-умолчанию, вызывая where с двумя параметрами (название столбца и значение), они будут соединены, используя оператор равенства (=). Например, вызов where('name', 'Fred') вернет следующее: WHERE name = "Fred".

Если ваш стиль написания кода направлен на ясность написанного, а не на краткость, то можно использовать метод where_equal идентичный методу where.

Метод where_not_equal добавляет пункт WHERE column != "value" к вашему запросу.

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

<?php
$people = ORM::for_table('person')
            ->where(array(
                'name' => 'Fred',
                'age' => 20
            ))
            ->find_many();

// Создаст следующий запрос SQL:
SELECT * FROM `person` WHERE `name` = "Fred" AND `age` = "20";

Короткая запись: where_id_is¶

Это простой вспомогательный метод, для составления запроса по первичному ключу таблицы. Смотрит относительно ID столбца, указанного в конфигурации. Если вы используете составной первичный ключ, то нужно передать массив, где ключом является название столбца. Столбцы, не принадлежащие к этому ключу будут игнорироваться.

Короткая запись: where_id_in¶

Этот вспомагательный метод аналогичен where_id_is, но он ожидает массив первичных ключей для выборки. Так же понимает и составной первичный ключ.

Меньше чем / больше чем: where_lt, where_gt, where_lte, where_gte¶

Есть четыре метода, доступные для неравенств:

• Меньше чем (less than): $people = ORM::for_table('person')->where_lt('age', 10)->find_many();
• Больше чем (greater than): $people = ORM::for_table('person')->where_gt('age', 5)->find_many();
• Меньше или равен (less than or equal): $people = ORM::for_table('person')->where_lte('age', 10)->find_many();
• Больше или равен (greater than or equal_: $people = ORM::for_table('person')->where_gte('age', 5)->find_many();

Сравнение строк: where_like и where_not_like¶

Для добавления пункта WHERE ... LIKE, используйте:

<?php
$people = ORM::for_table('person')->where_like('name', '%fred%')->find_many();

Аналогично и для WHERE ... NOT LIKE, используйте:

<?php
$people = ORM::for_table('person')->where_not_like('name', '%bob%')->find_many();

Множественные условия OR¶

Можно добавить простое условие OR в тот же пункт WHERE используя where_any_is. Если вам нужно указать множество условий, используйте массив элементов. Каждый элемент будет ассоциативным массивом, содержащим множество условий.

<?php
$people = ORM::for_table('person')
            ->where_any_is(array(
                array('name' => 'Joe', 'age' => 10),
                array('name' => 'Fred', 'age' => 20)))
            ->find_many();

// Создаст SQL запрос:
SELECT * FROM `widget` WHERE (( `name` = 'Joe' AND `age` = '10' ) OR ( `name` = 'Fred' AND `age` = '20' ));

По-умолчанию, оператор равенства используется для каждого столбца, но его можно переопределить для любого столбца, используя второй параметр:

<?php
$people = ORM::for_table('person')
            ->where_any_is(array(
                array('name' => 'Joe', 'age' => 10),
                array('name' => 'Fred', 'age' => 20)), array('age' => '>'))
            ->find_many();

// Создаст SQL запрос:
SELECT * FROM `widget` WHERE (( `name` = 'Joe' AND `age` > '10' ) OR ( `name` = 'Fred' AND `age` > '20' ));

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

<?php
$people = ORM::for_table('person')
            ->where_any_is(array(
                array('score' => '5', 'age' => 10),
                array('score' => '15', 'age' => 20)), '>')
            ->find_many();

// Создаст SQL запрос:
SELECT * FROM `widget` WHERE (( `score` > '5' AND `age` > '10' ) OR ( `score` > '15' AND `age` > '20' ));

Определение принадлежности: where_in и where_not_in¶

Для добавления пунктов WHERE ... IN () или WHERE ... NOT IN (), используйте методы where_in и where_not_in соответственно.

Оба метода принимают два аргумента. Первый - название столбца, с которым сравнивать. Второй - массив возможных значений. Как и во всех методах where_, вы можете указать множество столбцов, используя ассоциативный массив в качестве параметра.

<?php
$people = ORM::for_table('person')->where_in('name', array('Fred', 'Joe', 'John'))->find_many();

Работа с NULL значениями: where_null и where_not_null¶

Для добавления пункта WHERE column IS NULL или WHERE column IS NOT NULL, используйте методы where_null и where_not_null соответственно. Оба метода принимают один параметр: название столбца для сравнения.

Необработанный WHERE¶

Если вам необходимо создать более сложный запрос, то можно использовать метод where_raw для указания нужного SQL-фрагмента для пункта WHERE. Данный метод принимает два аргумента: строку, добавляемую к запросу, и (опционально) массив параметров, который будет связан со строкой. Если параметры были переданы, строка должна содержать знаки вопроса (?) как плейсхолдеры, для подстановки вместо них значений из массива, а массив должен содержать значения, которые будут подставлены в строку в соответствующем порядке.

Данный метод можно использовать в цепочке методов вместе с другими методами where_* а так же с методами вроде offset, limit и order_by_*. Содержимое переданной строки будет соединено с предыдущими и последующими пунктами WHERE с AND в качестве соединения.

<?php
$people = ORM::for_table('person')
            ->where('name', 'Fred')
            ->where_raw('(`age` = ? OR `age` = ?)', array(20, 25))
            ->order_by_asc('name')
            ->find_many();

// Создаст SQL запрос:
SELECT * FROM `person` WHERE `name` = "Fred" AND (`age` = 20 OR `age` = 25) ORDER BY `name` ASC;

Обратите внимание, что этот метод поддерживает только синтакс “плейсхолдера в виде вопроса”, а НЕ синтакс “именной плейсхолдер”. Все потому, что PDO не позволяет создавать запросы, содержащие смешанные типы плейсхолдеров. Так же, необходимо убедиться в том, что число вопросов-плейсхолдеров в строке соответствует числу элементов в массиве.

Если вам нужно ещё больше гибкости, вы можете вручную указать всю строку запроса. Смотрите Необработанные запросы ниже.

Limit и offset¶

Обратите внимание, что эти методы **не* экранируют свои паораметры в запросе, поэтому они не должны передаваться напрямую от пользователя.*

Методы limit и offset очень похожи на эквивалентные им в SQL.

<?php
$people = ORM::for_table('person')->where('gender', 'female')->limit(5)->offset(10)->find_many();

Порядок¶

Обратите внимание, что эти методы **не* экранируют свои паораметры в запросе, поэтому они не должны передаваться напрямую от пользователя.*

Доступны два метода для добавления к запросу пункта ORDER BY. Это order_by_desc и order_by_asc, каждый из которых принимает название столбца для сортировки. Имена столбцов будут писаться в кавычках.

<?php
$people = ORM::for_table('person')->order_by_asc('gender')->order_by_desc('name')->find_many();

Если вы хотите упорядочить по какому-то другому признаку, отличному от названия столбца, то используйте метод order_by_expr для добавления SQL выражения без кавычек, как в пункте ORDER BY.

<?php
$people = ORM::for_table('person')->order_by_expr('SOUNDEX(`name`)')->find_many();

Короткая запись для указания множества столбцов¶

select_many и select_many_expr очень похожи, но позволяют указать более одного столбца за раз. Например:

<?php
$people = ORM::for_table('person')->select_many('name', 'age')->find_many();

В результате сформирует запрос:

<?php
SELECT `name`, `age` FROM `person`;

Для указания алиасов, вам нужно передать массив (алиас будет называться так же, как ключ в ассоциативном массиве):

<?php
$people = ORM::for_table('person')->select_many(array('first_name' => 'name'), 'age', 'height')->find_many();

В результате сформирует запрос:

<?php
SELECT `name` AS `first_name`, `age`, `height` FROM `person`;

Вы можете использовать такой стиль при передаче аргументов в select_many и select_many_expr путем смешивания и сопоставления массивов и параметров:

<?php
select_many(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5')
select_many('column', 'column2', 'column3')
select_many(array('column', 'column2', 'column3'), 'column4', 'column5')

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

<?php
$people = ORM::for_table('person')->select_many('name', 'age', 'height')->select_expr('NOW()', 'timestamp')->find_many();

В результате сформирует запрос:

<?php
SELECT `name`, `age`, `height`, NOW() AS `timestamp` FROM `person`;

Необработанные соединения JOIN¶

Если вам нужно построить более сложный запрос, то можно использовать метод raw_join для указания SQL-фрагмента для пункта JOIN. Этот метод принимает четыре обязательных аргумента: строку, добавляемую к запросу, условия в виде массива, содержащего три компонента: первый столбец, оператор, второй столбец, алиас таблицы и (необязательно) массив параметров. Если параметры переданы, строка должна содержать знаки вопроса (?) для представления подставляемых значений, и массив параметров должен создержать значения для подстановки в строку в корректной последовательности.

Этот метод может использоваться в цепочке наравне с другими методами *_join так же, как и методы вроде offset, limit и order_by_*. Содержимое переданной строки будет соединено с предшествующими и последующими пунктами JOIN.

<?php
$people = ORM::for_table('person')
            ->raw_join(
                'JOIN (SELECT * FROM role WHERE role.name = ?)',
                array('person.role_id', '=', 'role.id'),
                'role',
                array('role' => 'janitor'))
            ->order_by_asc('person.name')
            ->find_many();

// Создаст SQL запрос:
SELECT * FROM `person` JOIN (SELECT * FROM role WHERE role.name = 'janitor') `role` ON `person`.`role_id` = `role`.`id` ORDER BY `person`.`name` ASC

Обратите внимание, этот метод поддерживает только синтаксис “плейсхолдеров в виде знака вопроса”, а не синтаксис “именованных плейсхоледров”. Потмоу что PDO не позволяет создавать запросы с различным типом плейсхоледров. Так же нужно убедиться, что число знаков вопроса в строке совпадает с числом передаваемых значений в массиве.

Если вам нужно ещё больше гибкости, вы можете вручную написать весь запрос. Смотрите Необработанные запросы ниже.

Свойства, содержащие выражения¶

Можно задать свойства модели, содержащие выражения из базы данных, используя метод set_expr.

<?php
$person = ORM::for_table('person')->find_one(5);
$person->set('name', 'Bob Smith');
$person->age = 20;
$person->set_expr('updated', 'NOW()');
$person->save();

Значение у updated столбца будет вставлено в запрос в чистом виде, позволяя тем самым базе данных выполнить любую нужную нам функцию - в данном случае NOW().

Примечания¶

• Нет поддержки объединений (join) по подключениям
• Множественные подключения не делятся настройками конфигурации. Это означает, что если у одного соединения параметр логов имеет значение true а у другого нет, то только запросы из соединения со включенным логом будут доступны для методов ORM::get_last_query() и ORM::get_query_log().
• Был добавлен новый метод, ORM::get_connection_names(), возвращающий массив с именами соединений.
• Кэширование должно работать со множеством соединений (не забудьте включить кеширование для каждого соединения), однако это не надежно в отношении unit-тестирования. Пожалуйста, сообщайте об ошибках.