Введение в Active Records

С большинством классов вы будете работать во время использования Узлов, а Элементы Содержимого будут расширять \IPS\Patterns\ActiveRecord. Объекты этого класса представляют собой строку в таблице базы данных. Очень важно, чтобы вы использовали методы, предоставляемые этим классом, а не вызывали базу данных напрямую, так как если Вы добавите дополнительные функции к элементу содержимого, методы будут выполнять более сложные задачи.

static load( int $id )

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

Результаты кэшируются, поэтому если вы загрузите один и тот же элемент дважды, второй запрос не будет сделан к базе данных, оба вызова вернут один и тот же объект (тот же объект по упоминанию - не копия объекта).

Например:

$item = YourClass::load( 1 );

static constructFromData( array $data )

Если по какой-то причине вам необходимо выбрать данные непосредственно из базы данных (например, если вы хотите получить самые последние записи), и у вас есть массив, содержащий строки из базы данных, метод constructFromData позволяет создать объект из этих данных, без вызова load, который сделает другой (ненужный) запрос к базе данных.

Например:

$item = YourClass::constructFromData( \IPS\Db::i()->select(...)-
>first() );

__get( mixed $key ) __set( mixed $key, mixed $value )

Несмотря на то, что вы не вызываете эти методы непосредственно - "волшебные" методы get и set  позволяют получить и установить данные в строке базы данных.

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

Например, предположим, что ваша таблица базы данных выглядит так:

Вы установите $databasePrefix:

static $databasePrefix = 'item_';

Вы будете загружать первый ряд подобным образом (он автоматически будет искать колонки, с названием “id”):

$item = YourClass::load( 1 ); 

Если вы хотите изменить поведение какой-либо определенной колонки (например, если у вас есть колонка базы данных, которая хранит значение timestamp, и вы хотите чтобы getter/setter обрабатывал объекты \IPS\DateTime) вы можете определить методы, называемые get_<key> и set_<key>. В этих методах свойство $_data хранит исходные значения. Например:

public function get_date() {
return \IPS\DateTime::ts( $this->_data[‘date’] );
}

public function set_date( $value ) {
$this->data[‘date’] = $value->getTimestamp();
}

save()

После изменения любых свойств, вы должны вызвать метод save, чтобы фактически сохранить эти изменения в базе данных:

$item = YourClass::load( 1 );
$item->title = 'New Title';
$item->save();

delete()

Метод delete удаляет элемента из базы данных. Например:

$item = YourClass::load( 1 );
$item->delete();

 __clone()

Есть отличный метод, который автоматически подстраивает первичный ключ, если Вы клонируете элемент. Пример:

$item = YourClass::load( 1 );
$copy = clone $item;
$copy->save();
echo $item->id; // 4

Битовые флаги

Класс ActiveRecord содержит специальные функции для облегчения побитовой работы, что позволяет использовать одну колонку INT в базе данных для хранения нескольких двоичных значений.

Чтобы сделать это, Вы можете следующим образом определить статическое свойство $bitOptions в своем классе:

public static $bitOptions = 
	array( 'bitwise_column' => 
	array(
		'bitwise_column' => array( 
			'property_1'	=> 1,
			'property_2'	=> 2,
			'property_3'	=> 4,
		),
	),
);

В этом примере есть столбец в базе данных (bitwise_column), в котором хранятся побитовые данные (если вам нужно хранить значения немного большие, чем могут храниться в едином поле INT, вы можете добавить дополнительные столбцы). Этот столбец сохраняет 3 логических значения (property_1, property_2 и property_3). При определении свойств, вы должны определить числовым значением, которое их представляет, поэтому номер должен каждый раз удваиваться (1, 2, 4, 8, 16, и т.д.).

ActiveRecord будет автоматически предоставлять объект \IPS\Patterns\Bitwise для этой колонки, которая использует \ArrayAccess. Вы можете получить и установить значения, как если бы они были массивом:

/ * Получение значения * /
if ( $object->bitwise_column[‘property_1’] ) {
// . . .
}

/* Настройка */
$object->bitwise_column[‘property_2’] = FALSE;
$object->save();

/* Получение срок из базы */
$rowsWithPropery1AsTrue = \IPS\Db::i()->select( ‘*’, ‘table’, \IPS
\Db::i()->bitwiseWhere( \IPS\YourClass::
$bitOptions['bitwise_column'], 'property_1' ));

Заметки

Определение класса

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

loadAndCheckPerms

Существует метод loadAndCheckPerms( int $id ),который является общим для всех классов, рассматриваемых в данном документе, хотя он не является частью \IPS\Patterns\ActiveRecord.

По умолчанию он ведет себя так же, как метод load( int $id ), предоставленный \IPS\Patterns\ActiveRecord, тем не менее, если Вы добавляете дополнительные функции, проверьте соответствующие разрешения. Например, после того, как вы примените права доступа клиентского уровня, выскочит OutOfRangeException, если у вошедшего в данный момент пользователя нет прав на просмотр объекта. Аналогичным образом, после того как вы реализовали скрытие содержимого, будет появляться OutOfRangeException, если происходит загрузка скрытого объекта, а у вошедшего в данный момент пользователя нет прав на просмотр скрытых объектов.

Таким образом, вы всегда должны использовать метод через load( int $id ) при загрузке узлов, элементов содержимого, комментариев и обзоров в клиентской части, или для любого кода, вызываемого из фронт-энда.