Курсор

Этот класс (Cursor) является абстрактной основой реализации Active Record , которая используется всеми Data mapper F3.

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

Пространство имен: \DB Расположение файла:lib/db/cursor.php

Методы

Следующие методы доступны для Data mapper'ов. Даже если синтаксис фильтра и опции может отличаться от одного mapper'a к другому, эти функции делают одно и то же. Таблицу ниже будем брать как исходный набор данных для всех послежующих примеров.

ID title text author
1 F3 for the win Use It Now! 49
2 Once upon a time there was a dragon. 2
3 Barbar the Foo foo bar 25
4 untitled lorem ipsum 8

load

Сопоставить с первой записью, соответствующей критериям

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

Метод load сопоставляет объект mapper'а с записями. Вы можете определить, $filter чтобы загружать только те записи, которые вам нужны.

Он использует find () для загрузки записей и делает первую запись (объект mapper'а), которая соответствует критериям, активной. Дополнительные записи, соответствующие тем же критериям, можно сделать активной, перемещая указатель курсора (т.е. с помощью skip () ).

Вы можете найти подробные описания $filter и $option синтаксиса на Mapper конкретных страниц: Jig Mapper , Монго Mapper и SQL Mapper .

Аргумент $ttl, если он указан , позволяет кэшировать результат загрузки mapper'а, при условии что CACHE включен.

Начнем с простого примера, в котором мы не указываем никакого фильтра, поэтому будет загружена первая запись:

$mapper->load();  // by default, loads the 1st record and makes it active
echo $mapper->title; // displays 'F3 for the win'

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

Класс Cursor расширяется классом Magic . Это означает, что вы можете получить данные с полей так же, как с любого свойства объекта или массива:

echo $mapper->title; // 'F3 for the win'
echo $mapper['text']; // 'Use It Now!'
echo $mapper->get('author'); // 49

next

Перейти к следующей записи

mixed next ( )

Когда объект mapper'а сопоставляется, его внутренний указатель курсора указывает на одну запись. Чтобы переместить указатель к следующей записи,используете next().

$mapper->load();
echo $mapper->title; // 'F3 for the win'
$mapper->next();
echo $mapper->title; // 'Once upon a time'

Внутри, класс Cursor выбирает все записи из базовой базы данных, соответствующие $filter, указанному при вызове load(). Любая попытка перехода к следующей, предыдущей, первой или последней записи просто переместит внутренний указатель, тем самым уменьшив дисковый ввод-вывод.

prev

Сопоставить с предыдущей записью

mixed prev ( )

first

Сопоставить с первой записью в курсоре

mixed first ( )

last

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

mixed last ( )

skip

Сопоставить с n-й записью относительно текущей позиции курсора

mixed skip ( [ int $ofs = 1 ] )

dry

Вернуть TRUE, если текущая позиция курсора не сопоставлена ни с одной записью

bool dry ( )

Это ,в каком-то смысле, «пустая» функция. Он возвращается TRUE, если курсор не сопоставлен ни с одной записью базы данных, даже если записи были load отредактированы.

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

$mapper->load();  // by default, loads the 1st record
 
while ( !$mapper->dry() ) {  // gets dry when we passed the last record
	echo $mapper->title;
	// moves forward even when the internal pointer is on last record
	$mapper->next();
}

findone

Вернуть первую запись (объект mapper'а), которая соответствует критериям

object|FALSE findone ( [ string|array $filter = NULL [, array $options = NULL [, int $ttl = 0 ]]] )
 

Используйте этот метод, если вы хотите обработать только один объект в своей бизнес-логике. Полезная команда для обработки load'ом() только одной записи.

Смотрите метод load() для подробной информации по параметрам.

paginate

Возвращает подмножество записей с дополнительной информацией о разбиении на страницы

array paginate ( [ int $pos = 0 [, int $size = 10 [, string|array $filter = NULL [, array $options = NULL [, int $ttl = 0]]]]] )

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

Например:

// page 1
$result = $mapper->paginate(0, 3);
/*
array(4) {
	["subset"] => array(3) {
		[0] => mapper object, #ID: 1, title: F3 for the win
		[1] => mapper object, #ID: 2, title: Once upon a time
		[2] => mapper object, #ID: 3, title: Barbar the Foo
	}
	["total"] => int(4)
	["limit"] => int(3)
	["count"] => float(2)
	["pos"] => int(0)
}
*/
 
// page 2
$result = $mapper->paginate(1, 3);
/*
array(4) {
	["subset"] => array(1) {
		[0] => mapper object, #ID: 4, title: untitled
	}
	["total"] => int(4)
	["limit"] => int(3)
	["count"] => float(2)
	["pos"] => int(1)
}
*/

Ключ subset содержит массив объектов Mapper ,которые вернул find(). total - это сумма всех записей для всех страниц. limit содержит то же значение, что и входной параметр вызова size. count - количество доступных подмножеств/страниц. pos дает вам текущую позицию курсора подмножества (это номер страницы - 1).

loaded

Вернуть количество загруженных записей

int loaded ( )

save

Сохранить сопоставленную запись

mixed save ( )

Этот метод сохраняет данные в базе данных. Класс Cursor автоматически определяет, запись должна быть обновлена или записана в качестве новой записи, на основании возвращаемого значения dry.

erase

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

int|bool erase ( )

reset

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

NULL reset ( )

Handlers событий

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

Примечание: если вы расширите mapper и попытаетесь прочитать или изменить его поля (особенно те, которые существуют как свойство класса) с помощью magic getter/setter внутри этих обработчиках событий, вы получите непредсказуемый результат или ошибку.

Простым решением этой проблемы является использование методов getили setвнутри дочернего класса. Они безопасны в использовании и не отменяют защищенные свойства.

class Model extends \DB\SQL\Mapper {
    function __construct(){
        parent::__construct(\Base::instance()->get('DB'),'test_model');
        $this->beforeinsert(function($self){
            $self->source='bar'; // fails due to protected property named 'source'
            $self->set('source','bar'); // works - just use the setter directly
        });
}}

Обратитесь к FatFree GitHub Issue # 697 для получения дополнительных сведений.

onload

Определите hook для события onload

hook будет выполняться каждый раз при загрузке mapper'а. Например, он будет выполненяться один раз после вызова load(), next() или prev(), или будет выполненяться для каждого mapper'а, возвращенного find().

callable onload ( callable $func )

Функция hook принимает 1 аргумент: объект mapper'а. Например:

$mapper->onload(function($self){
  //do something
});

beforeinsert, afterinsert

Определение hooks для событий beforeinsert и afterinsert

hook beforeinsert будет выполняться непосредственно перед каждой командой INSERT и могут прервать событие, вернув false.

hook afterinsert будет выполняться сразу после каждой командой INSERT.

callable beforeinsert ( callable $func )
callable afterinsert ( callable $func )

Каждая функция hook принимает 2 аргумента: объект mapper'а и значение(-я) первичного ключа(-ей). Например:

$mapper->beforeinsert(function($self,$pkeys){
  //do something before inserting
});
$mapper->afterinsert(function($self,$pkeys){
  //do something after inserting
});

beforeupdate, afterupdate

Определение hooks для событий beforeupdate и afterupdate

hook beforeupdate будет выполняться непосредственно перед каждой командой UPDATE и могут прервать событие, вернув false.

hook afterupdate будет выполняться сразу после каждой командой UPDATE.

callable beforeupdate ( callable $func )
callable afterupdate ( callable $func )

Каждая функция hook принимает 2 аргумента: объект mapper'а и значение(-я) первичного ключа(-ей). Например:

$mapper->beforeupdate(function($self,$pkeys){
  //do something before updating
});
$mapper->afterupdate(function($self,$pkeys){
  //do something after updating
});

beforesave, aftersave

Определение hooks для событий beforeinsert, beforeupdate, afterinsert и afterupdate

hook beforesave будет выполняться перед каждой командой INSERT или UPDATE и могут прервать событие, вернув false.

hook aftersave будет выполняться сразу после каждой командой INSERT или UPDATE.

callable beforesave ( callable $func )
callable aftersave ( callable $func )

Каждая функция hook принимает 2 аргумента: объект mapper'а и значение(-я) первичного ключа(-ей). Например:

$mapper->beforesave(function($self,$pkeys){
  //do something before inserting or updating
});
$mapper->aftersave(function($self,$pkeys){
  //do something after inserting or updating
});

beforeerase, aftererase

Определение hooks для событий beforeerase и aftererase

hook beforerase будет выполняться перед любой командой DELETE и может прервать событие, вернув false.

hook aftererase будет выполняться сразу после любой командой DELETE.

callable beforeerase ( callable $func )
callable aftererase ( callable $func )

Каждая функция hook принимает 2 аргумента: объект mapper'а и значение(-я) первичного ключа(-ей). Например:

$mapper->beforeerase(function($self,$pkeys){
  //do something before deleting
});
$mapper->aftererase(function($self,$pkeys){
  //do something after deleting
  echo 'the id of the deleted row was '.$pkeys['id'];
});

Примечание: обратите внимание, что erase hook могжет выполняться только при использовании $mapper→erase();на загруженном/сопоставленном mapper'e. Если вы собираетесь стереть весь набор, указав $filter в методе erase, эти hooks событий будут пропущены.

oninsert, onupdate, onerase

Предусмотрены для обратной совместимости, они являются псевдонимами для afterinsert(), afterupdate()и aftererase().

Абстрактные методы

Следующие методы должны быть реализованы всеми классами, которые были расширены mapper'ом, для правильной работы.

find

Возвращает записи (массив объектов mapper'а), соответствующие критериям

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

Смотрите метод load() для подробной информации по параметрам.

insert

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

array insert ( )

update

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

array update ( )
Печать/экспорт