SQL Mapper

SQL Object-Relational-Mapper - это реализация абстрактного класса курсора Active Record .

Пространство имен: \DB\SQL

Расположение файла:lib/db/sql/mapper.php

Инициализация

Чтобы использовать SQL ODM, создайте соединение SQL DB. Например:

$mapper = new \DB\SQL\Mapper(\DB\SQL $db, string $table [, array|string $fields = NULL [, int $ttl = 60 ]] )
 

Аргумент $fields позволяет указать только те поля , которые нужно отобразить. $fields представляет собой либо массив, либо список (в соответствии с функцией F3 split) имен столбцов, которые необходимо включить в mapper. По умолчанию для всех столбцов.

Когда $ttl! = 0, запускается проверка кэша для предыдущей схемы, и если срок ее действия истек или не найден, текущий результат сохраняется в бэкэнде кэша при условии, что система CACHE включена.

Eсли вы хотите создать класс модели, вы можете завершить его:

$f3->set('DB',new DB\SQL('sqlite:db/database.sqlite'));
 
class User extends \DB\SQL\Mapper {
	public function __construct() {
		parent::__construct( \Base::instance()->get('DB'), 'users' );
	}
}
 
$user = new User();
$user->load('id = 1');
// etc.

Синтаксис

$ filter

Аргумент $filter для SQL принимает следующую структуру:

  • строковое значение для простых строк where
string $whereClause
 
  • значение массива для параметризованных запросов
array ( string $whereClause [, string $bindValue1 [, string $bindValue2 [, ... ]]] )
 

Параметризованные запросы

Рекомендуется использовать параметризованные запросы для всех условий where, которые вводит пользователь.

Пример с параметром в виде вопросительного знака:

$mapper->load(array('username = ? and password = ? and deleted = 0','John','acbd18db4cc2f85cedef654fccc4a4d8'));

И с именованными параметрами:

$mapper->load(array(
	'username = :user and password = :pass and deleted = 0',
	':user'=>'John',':pass'=>'acbd18db4cc2f85cedef654fccc4a4d8'
));

Из-за ограничения PDO нельзя использовать именованный параметр более одного раза в запросе. Вам нужно создать 2 параметра :user1 и :user2 и передать им одинаковое значение.

В одном операторе SQL нельзя использовать и именованные параметры, и вопросительные знаки как параметры; выберите тот или иной вид параметра, но не смешивайте.

Тип данных, определяемый пользователем

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

array(
	'prize > :prize and active = 1',
	':prize' => array(123, \PDO::PARAM_INT)
)
 

Когда вы используете оператор LIKE в условии where, обратите внимание, что знак % не входит в критерии where, но входит в параметр привязки следующим образом:

$user->find(array('email LIKE ?','%gmail%')); // returns all users with an email address at GMAIL

Полнотекстовый поиск

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

$text = 'some text';
$mapper->find(["MATCH (name,code) AGAINST (:search IN BOOLEAN MODE)", ':search' => $text ]);

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

$mapper->relevance = "MATCH (name,code) AGAINST (:search1 IN BOOLEAN MODE)";
$mapper->find(["MATCH (name,code) AGAINST (:search2 IN BOOLEAN MODE)", ':search1' => $text, ':search2' => $text ], ['order'=>'relevance desc']);

И если вы хотите сопоставить сразу несколько ключевых слов, вам нужно обернуть и экранировать ключевые слова

$mapper->find(["(MATCH(fieldA,fieldB) AGAINST('(".implode('") ("',$keywords).")' IN BOOLEAN MODE )"]);

или вставьте несколько заполнителей:

$mapper->find(["(MATCH(fieldA,fieldB) AGAINST('(?) (?) (?)' IN BOOLEAN MODE )", $a, $b, $c]);

$ option

$option для SQL принимает следующую структуру:

array(
	'order' => string $orderClause,
	'group' => string $groupClause,
	'limit' => integer $limit,
	'offset' => integer $offset
)
 

то есть:

array(
	'order' => 'score DESC, team_name ASC',
	'group' => 'score, player',
	'limit' => 20,
	'offset' => 0
)
 

Методы

table

Вернуть имя сопоставленной таблицы

string table()
  

exists

Вернет TRUE, если данное поле определено

bool exists( string $key )

changed

Вернет TRUE, если какое-либо из указанное значение поля изменилось

bool changed ( [ string $key = NULL ] )
 

set

Присвоить заданное значение полю

scalar set( string $key, scalar $val )
 

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

$mapper->foo = 'bar';
$mapper['foo'] = 'bar';

Виртуальные поля

Если вы установите новое значение для пустого/не сопоставленного mapper'а, вы создадите на нем виртуальное поле. Вы можете добавить в свой запрос несколько агрегатных функций:

$scores = new Scores();
$scores->sum_score = 'SUM(score)';
$scores->avg_score = 'AVG(score)';
$scores->load(null,array('group'=>'player_id'));
echo $scores->sum_score; // returns the sum of all scores made by player_id
echo $scores->avg_score; // returns the avarage score of that player

get

Получить значение поля

scalar get( string $key )
 

Чтобы получить идентификатор последней вставленной строки или последнее значение из объекта последовательности, необходимо использовать зарезервированное $key со значением '_id':

$lastInsertedID = $mapper->get('_id'); // get the ID of the last inserted row or the last value from a sequence object

clear

Очистить значение поля

NULL clear( string $key )
 

type

Получить имя типа PHP, эквивалентного константе PDO

string type( string $pdo )
 

Этот метод преобразует константы заданных типов PDO в эквивалентные именованные типы PHP следующим образом:

switch ($pdo) {
	case \PDO::PARAM_NULL:
		return 'unset';
	case \PDO::PARAM_INT:
		return 'int';
	case \PDO::PARAM_BOOL:
		return 'bool';
	case \PDO::PARAM_STR:
		return 'string';
}

value

Привести значения к типу PHP

scalar value( string $type, scalar $val );

Этот метод позволяет вам преобразовать значение из БД в тип PHP. Этот метод преобразует типы PDO в эквивалентные типы PHP следующим образом:

switch ($type) {
	case \PDO::PARAM_NULL:
		return (unset)$val;
	case \PDO::PARAM_INT:
		return (int)$val;
	case \PDO::PARAM_BOOL:
		return (bool)$val;
	case \PDO::PARAM_STR:
		return (string)$val
 

cast

Вернуть поля объекта mapper'а как ассоциативный массив

array cast( [ object $obj = NULL ] );

select

Создать строку запроса и выполните ее

array select( string $fields [, string|array $filter = NULL [, array $options = NULL [, int $ttl = 0 ]]] );

find

Вернуть записи, соответствующие заданному критерию

array find( [ string|array $filter = NULL [, array $options = NULL [, int $ttl = 0 ]]] );

count

Подсчет записей, соответствующих заданному критерию

int count( [ string|array $filter = NULL [, $ttl=0 ]] )
 

insert

Вставить новую запись

object insert()
 

update

Обновить текущую запись

object update()
 

save

Обновить существующую запись или вставьте новую

object save()

Если одна или несколько записей были загружены в mapper, save будет использоваться метод update. Если в mapper'е в данный момент нет загруженных записей, save будет использован метод insert. Метод save часто используется в сочетании с методом copyfrom.

skip

Вернуть запись с указанным смещением, используя те же критерии, что и предыдущий вызов load (), и сделать ее активной.

array skip( [ int $ofs = 1 ] )
 

erase

Удалить текущую запись

int erase( [ string|array $filter = NULL ] )
 

Удаляет текущую запись mapper'а. Если $filter задано, он выполняет SQL команду DELETE FROM $this→table WHERE $filter для таблицы, указанной при создании экземпляра mapper'а. Обратите внимание, что hooks erase событий пропускаются, если $filter присутствует.

reset

Сбросить курсор

NULL reset( )
 

copyfrom

Сопоставить объект mapper'а с помощью массива

NULL copyfrom( array | string $var [, callback $func = NULL ] )
 

Этот метод позволяет сопоставить элементы массива из hive с БД в таблице которой имена полей соответсвуют именам ключей этого массива.

$func- это функция обратного вызова, которую можно применить к переменной массива hive. Как объясняется в Руководстве пользователя баз данных , ключи массива должны иметь имена, идентичные свойствам объекта mapper'а. Это позволяет, например, сопоставить объект mapper'а с полями формы POSTed:

$f3->get('user')->copyfrom('POST'); // F3 synch the 'POST' hive array variable with the $_POST array

По умолчанию copyfrom принимает весь предоставленный массив; в нашем примере выше - весь POST из <form>. Так что, если кто-то изменяет или подделывает вашу форму, добавляя некоторые дополнительные поля <input> в вашу DOM с помощью таких инструментов, как, например, firebug, можно перезаписать, например, идентификатор записи, роль прав доступа или что-то еще… Довольно большая утечка безопасности . К счастью, F3 предлагает вам универсальное решение с помощью функции обратного вызова, которую вы можете использовать для применения любой предварительной обработки к переменной массива hive, такой как нормализация значений и/или фильтрация и ограничение полей для копирования. Ваша функция обратного вызова получит переменную массива hive и должна аналогичным образом вернуть массив пар ключей/значений: поля, которые необходимо передать объекту сопоставления.

Хорошо давай сделаем это. Например, давайте использовать функцию фильтра обратного вызова, сохраняющую только поля «имя» и «возраст»:

$db = new DB\SQL('sqlite:db/ent.sqlite');
$f3->set('user',new DB\SQL\Mapper($db,'users'));
$f3->get('user')->copyfrom('POST',function($val) {
	// the 'POST' array is passed to our callback function
    return array_intersect_key($val, array_flip(array('name','age')));
});
$f3->get('user')->save();
});

Это оно! Поскольку F3 дезинфицирует значения, с такой дополнительной фильтрацией ваша БД защищена от инъекций.

copyto

Заполнить переменную массива hive полями mapper'a

NULL copyto( string $key )
 

fields

Вернуть имена полей

array fields( bool $adhoc = TRUE )
 

Этот метод возвращает все доступные поля для этого mapper'а.Если $adhoc установить в FALSE ,то виртуальные поля не будут возвращаться. Этот метод будет учитывать любые ограничения на поля, которые были установлены во время создания экземпляра .

schema

Вернуть схему таблицы

array schema( array $fields = null )
 

$fields представляет собой либо массив, либо список имен столбцов для включения в возвращаемую схему.

required

Вернуть TRUE, если поле не допускает значения NULL

bool required( string $field )
 

factory

Преобразовать массива в объект mapper'а

protected object factory( array $row )
 

Этот метод, с областью видимости protected, используется внутри метода select.

Печать/экспорт