Сообщаем о наличии связей в модели

Как мы помним, в модуле Sprig все используемые поля таблицы объявляются в методе _init(), и поля связей тут не исключение. Есть четыре класса для описания различных типов связей (тут все похоже на связи в ORM, так что я сильно их расписывать не буду):

• Sprig_Field_HasOne
• Sprig_Field_HasMany
• Sprig_Field_BelongsTo
• Sprig_Field_ManyToMany

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

1. Есть записи в блоге (модель blog).
2. Есть тэги, которые вешаются на записи блога (модель tag).
3. Есть пользователи (модель user).
4. Есть статистика по пользователям блога. Т.к. она не относится непосредственно к модели пользователя (мы предполагаем, что есть и другие модули, где используется user), выделяем ее в отдельную модель (userinfo).

В упрощенном виде схема получится примерно такая:

Схема таблиц

Тут использованы соглашения по умолчанию для ORM (первичный ключ называется `id`, внешние ключи формируются как название модели + суффикс `_id`, и т.д.). Какие модели мы в итоге получим? Давайте я сразу приведу их код, а после разберем типы связей по отдельности.

// пользователи
class Model_User extends Sprig
{
	protected function _init() {
		$this->_fields += array(
			'id'               => new Sprig_Field_Auto,
			'username'   => new Sprig_Field_Char,
			'email'         => new Sprig_Field_Email,
			'userinfo'      => new Sprig_Field_HasOne,
			'articles'       => new Sprig_Field_HasMany,
		);
	}
}
 
// статьи
class Model_Article extends Sprig
{
	protected function _init() {
		$this->_fields += array(
			'id'              => new Sprig_Field_Auto,
			'title'           => new Sprig_Field_Char,
			'text'           => new Sprig_Field_Text,
			'user'          => new Sprig_Field_BelongsTo,
			'tags'          => new Sprig_Field_ManyToMany,
		);
	}
}
 
// тэги
class Model_Tag extends Sprig
{
	protected function _init() {
		$this->_fields += array(
			'id'            => new Sprig_Field_Auto,
			'name'      => new Sprig_Field_Char,
			'articles'    => new Sprig_Field_ManyToMany,
		);
	}
}
 
// доп. информация о пользователях
class Model_Userinfo extends Sprig
{
	protected function _init() {
		$this->_fields += array(
			'id'       => new Sprig_Field_Auto,
			'data'   => new Sprig_Field_Text,
			'user'   => new Sprig_Field_BelongsTo,
		);
	}
}

Условно все поля можно разбить на две категории – реальные поля и псевдополя. Примеры реальных полей – `id`, `email` и `username` в модели Model_User, они присутствуют в таблице. Псевдополя являются результатом наличия связей с другими моделями. Например, поля `articles` и `userinfo`, которые не могут быть сохранены в БД в явном виде. Для них свойство $in_db установлено в FALSE. Не стоит путать внешний ключ (например, `user_id` в таблице `articles`) с псевдополем `user` – в первом случае мы просто работаем с численным значением, второй вариант дает возможность получить связанный объект.

HasOne

Примером данной связи будет наличие доп. информации у пользователя. В модели Model_User объявлено псевдополе $userinfo:

'userinfo'	=> new Sprig_Field_HasOne,

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

• Имя связанной модели `model` будет `userinfo` (по названию псевдополя).
• Имя внешнего ключа в той модели (`column`) определится как `user_id` (имя текущей модели + '_id').

Схема определения имени внешнего ключа не является жестко фиксированной – используется метод fk($table = NULL) модели. Вы можете его переопределить, чтобы, к примеру, возвращать ‘user_key‘. Кроме того, если в Вашей модели используется нестандартный первичный ключ (например ‘key‘), то по умолчанию метод pk() будет возвращать что-то вроде ‘user_key‘ вместо ‘user_id‘ – будьте внимательны!

Теоретически, теперь мы можем попробовать обратиться к свойству $user->userinfo:

$user = Sprig::factory('user', array('id' => 1));
echo $user->userinfo->load()->data;

К сожалению, результата не будет. Что-то не так? Методом проб и ошибок определяем, что метод load() не возвращает ожидаемое (а мы предполагаем модель Userinfo, где поле ‘user_id‘ равно 1). А проблема вот в чем – надо объявить данную связь на другой ее стороне, т.е. собственно в модели Userinfo. Это связь типа BelongsTo, так что имеет смысл перейти к ней.

BelongsTo

Через данный тип связи объявляем, что каждый объект Userinfo привязан к родительскому объекту User, в нашем случае через поле ‘user_id‘. Так как пока что все свойства рассматриваемых моделей (ключи, имена связей и т.д.) максимально простые, то и объявление будет коротким:

'user'   => new Sprig_Field_BelongsTo,

Автоматически заполняются свойства связи:

• ‘model‘ – имя связанной модели, в данном случае ‘user‘.
• ‘column‘ – имя поля внешнего ключа, получаем через метод fk() модели Model_User (по умолчанию вернет ‘user_id‘).

Поскольку данный тип связи используется не только для HasOne, но и с HasMany, аналогичное объявление мы сделали в модели Model_Article для связи с Model_User:

'user'   => new Sprig_Field_BelongsTo,

Теперь можно вызывать $userinfo->user->load()->username, причем обратную сторону связи в данном случае прописывать необязательно. Таким образом, делаем вполне логичный вывод – связь обязательно должна быть прописана в пассивной модели (т.е. в модели, в которую переходит внешний ключ).

HasMany

Собственно тут тоже ничего сложного, вот так в Model_User объявлено, что каждый пользователь может понаписать множество статей в блоге:

'articles'       => new Sprig_Field_HasMany,

“На автопилоте” определяется свойство ‘model‘ – имя модели, получаем как название связи в единственном числе (через Inflector::singular()) – ‘article‘. Свойство ‘column‘ бессмысленно, т.к. в результате данной связи в таблице никаких полей не добавляется.

ManyToMany

Тут тоже все просто и скучно, в модели Model_Article объявляем о тэгах:

'tags'          => new Sprig_Field_ManyToMany,

• Свойство ‘model‘ получится как ‘tag‘ (имя связи в единственном числе).
• Свойство ‘through‘ (имя промежуточной таблицы) вычисляется аналогично ORM: берем имена таблиц (в данном случае это ‘articles‘ и ‘tags‘), ставим по алфавиту и разделяем знаком подчеркивания, т.е. ‘articles_tags‘ в итоге.
• Свойство ‘column‘ не заполняется ввиду неактуальности.

Что любопытно – после вычисления свойства ‘through‘ для пары статья-тэг становится доступным статическое свойство Sprig::$_relations['article_tag'], которое содержит имя промежуточной таблицы. Таким образом, если из модели Model_Tag обратиться к свойству articles, промежуточная таблица будет взята оттуда. Теоретически это должно позволить менять одну из главных настроек связи ManyToMany только в одном месте, но у меня это не вызвало особого интереса. Наверное проще указать ‘through‘ вручную в двух моделях, зато это будет предсказуемо.

Ленивая загрузка

Наверняка вы обратили внимание на метод load(), который иногда используется после обращения к связанным объектам. Очевидно, что данный метод вызывает загрузку записей, т.е. непосредственно $user->userinfo, к примеру, вернет только экземпляр Database_Query_Builder_Select с примененными параметрами выборки (с условием where('user_id', '=', 1)). В общем, lazy loading к вашим услугам! Правда, это актуально только для HasOne и BelongsTo.

Идем дальше. Наверняка вы помните, как осуществляется выборка связанных объектов в ORM. К примеру, $user->articles->where('approved', '=', 1)->find_all() позволяет выбрать только утвержденные статьи пользователя. Однако в Sprig не все так просто. К сожалению, непосредственный вызов $user->articles приведет к выборке всех статей пользователя, метод where() здесь просто некуда “воткнуть”. Единственное, что предлагается нам – все тот же метод load(). В результате то, что в ORM получается достаточно элегантно, в Sprig выглядит несколько неуклюже:

$query = DB::select()->where('user_id', '=', $user->pk())->where('approved', '=', 1);
$articles = Sprig::factory('article')->load($query, FALSE);

Сперва подготовили условия (авторство и наличие флага “утверждено”), потом подставили в метод load(). Не забудьте про второй параметр, т.к. по умолчанию количество записей ограничивается одной. Впрочем, можно установить нужный лимит записей, например для разбивки на страницы (т.е. для пагинатора).

Это актуально и для безусловных выборок. Например, получаем всех пользователей:

$users = Sprig::factory('user')->load(NULL, FALSE);

Да, это работает. Но теряется вся красота и прозрачность, которая сопутствует ORM. Надеюсь, это будет исправлено в следующих коммитах.

Усложняем задачу

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

Список изменений следующий.

• Таблица articles_tags переименована в arttags.
• Первичный ключ в articles теперь называется articleid.
• Внешний ключ user_id переименован в author_id.

Теперь посмотрим, как изменятся коды моделей. Для начала разберемся с переименованием первичного ключа. Обычно (и в ORM мы используем такой подход) для этого есть специальное свойство $_primary_key. Но одна из особенностей Sprig – некоторые типы полей могут быть заранее обозначены как часть первичного ключа (их свойство $primary установлено в TRUE). Это действительно для поля Sprig_Field_Auto, поэтому поле `articleid` будет добавлено в свойство $_primary_key автоматически. Другое дело, что в методе _init(), где это поле объявляется, необходимо указать актуальное имя:

protected function _init() {
	$this->_fields += array(
		'articleid'			=> new Sprig_Field_Auto,
		...

Стоит обратить внимание, что текущая версия Sprig не осуществляет проверку при добавлении поля в список первичного ключа, так что в случае прописывания свойства $_primary_key вручную скорее всего одно и то же поле будет добавлено туда дважды.

Идем дальше. Для связи с пользователем модель Article теперь использует внешний ключ `author_id`. В связи с этим меняем объявление поля в методе _init():

'user'	=> new Sprig_Field_BelongsTo(array('column' => 'author_id'),

Как мы видим, чтобы переопределить дефолтные названия для внешних ключей, надо использовать параметр column. Сделаем еще одно изменение – пусть доступ к модели User будет осуществляться по псевдополю ‘author‘ (т.е. $article->author вместо $article->user, что более логично). Для этого надо переименовать имя поля, а также явно указать название связанной модели, которое ранее вычислялось автоматически:

'author'	=> new Sprig_Field_BelongsTo(array('model' => 'user', 'column' => 'author_id'),

Ну и напоследок – указываем в явном виде новое имя промежуточной модели для связи ManyToMany:

'tags'=> new Sprig_Field_ManyToMany(array('through' => 'arttags')),

Прописали? Проверяем, работает?! Ан нет, не работает. Вспомните алгоритм вычисления наименования внешнего ключа – по умолчанию все зависит от первичого ключа. Поэтому JOIN таблиц arttags и tags будет осуществляться по некорректному полю ‘article_articleid‘. Как этого избежать, я уже упоминал – надо переопределить метод fk(), чем нам и придется заняться:

public function fk($table = NULL)
{
	$key = 'article_id';
 
	if ($table)
	{
		if ($table === TRUE)
		{
			$table = $this->_table;
		}
		return $table.'.'.$key;
	}
 
	return $key;
}

Конечно, не самое красивое решение. Во первых, приходится копировать исходный метод полностью, а хотелось бы в полной мере попользоваться наследованием, дабы в своем методе (условно говоря) вычислить переменную $key (или сохранить ее в каком-нибудь свойстве с говорящим названием $_foreign_key) и далее вызвать parent::fk(). Кроме того, вдруг в какой-нибудь другой таблице внешний ключ будет переходить под другим названием? Единственное приходящее мне в данный момент решение – добавление switch ... case с перечислением известных вариантов значений для переменной $table (по крайней мере для ManyToMany метод fk() всегда использует данный параметр). Вспоминается поговорка про мышей и кактус

На этом все

Согласитесь, налицо существенные недостатки и никаких преимуществ перед ORM. Так почему я пишу о данном модуле, а не придумываю новый повод написать очередную статью про ORM? Намекну, что главная сила Sprig не в связях. Sprig удобен тем, что мы унифицируем работу с полями модели/таблицы – генерацию и обработку форм в первую очередь. Но это уже тема для следующей – итоговой – статьи, в которой я покажу, что нам собственно делать с предоставляемыми возможностями.

Как мы знаем, основная “фишка” ORM – прозрачная работа с таблицами БД. Т.е. мы можем не описывать имеющиеся в таблице поля, а обращаться к ним как к свойствам модели. Это становится возможным благодаря автоматическому запросу (SHOW COLUMNS, если говорить о MySQL) к таблице при создании модели, загружающему информацию о структуре таблицы. Впрочем, это не освобождает от необходимости объявлять связи с другими таблицами.

Возможно Вы не знаете – когда Ваша таблица примет окончательные очертания, можно прописать мета-данные о формате полей в статическом свойстве $_column_cache (это массив, используем ключ $this->_object_name), чтобы ORM не запрашивал их каждый раз. Проще всего “подсмотреть” эти данные (используя var_dump() или Kohana::dump()) и скопировать в $_column_cache.

А что же Sprig? Тут немного другая философия – каждое поле таблицы представлено отдельным объектом, потомком абстрактного класса Sprig_Field. Казалось бы, что тут выдумывать, поле оно и есть поле, делаем его строковым и не волнуемся ни о чем. Ан нет! Использование отдельных классов имеет ряд преимуществ:

• Многие типы полей имеют сложившиеся форматы вывода на экран (к примеру, дату обычно не выводят в формате UNIX timestamp). С помощью Sprig мы можем настроить форматирование любого используемого типа данных.
• Аналогично и с генерацией элементов форм. Никто не будет показывать поле логического типа (т.е. TRUE/FALSE) в виде текстового – тут нужен checkbox. Sprig позволяет описать параметры генерируемого поля, в том числе и перечень допустимых значений (для формирования выпадающего списка).
• Есть типовые ограничения (уникальность, NOT NULL и т.д.), которые приходится прописывать для каждого поля в свойствах валидации ($_filters, $_rules и $_callbacks). А в Sprig поля имеют дополнительные свойства, описывающие различные аспекты хранения их в БД (и они автоматом используются при валидации). Об этом я напишу чуть позже.

Из чего строится модель

Каждая модель должна быть потомком класса Sprig (кто бы сомневался) и реализовывать метод _init(), в котором собственно и описываются все поля таблицы. Например, вот что происходит в модели Sprig_Model_User (включена в дистрибутив Sprig):

protected function _init()
{
	$this->_fields += array(
		'id' => new Sprig_Field_Auto,
		'username' => new Sprig_Field_Char(array(
			'empty'  => FALSE,
			'unique' => TRUE,
			'rules'  => array(
				'regex' => array('/^[\pL_.-]+$/ui')
			),
		)),
		'password' => new Sprig_Field_Password(array(
			'empty' => FALSE,
		)),
		'password_confirm' => new Sprig_Field_Password(array(
			'empty' => TRUE,
			'in_db' => FALSE,
			'rules' => array(
				'matches' => array('password'),
			),
		)),
		'last_login' => new Sprig_Field_Timestamp(array(
			'empty' => TRUE,
			'editable' => FALSE,
		)),
	);
}

Поля хранятся в свойстве $_fields. Каждый экземпляр класса Sprig_Field может быть создан с передачей дополнительных параметров, так что на стандартные для выбранного типа настройки можно сверху “накатить” свои. Так, если автоинкрементное поле `id` создается с настройками по умолчанию (что уж там еще настраивать), то для поля `username` добавлено правило валидации (ключ ‘rules‘) и свойства поля из БД – NOT NULL (ключ ‘empty‘) и UNIQUE (ключ ‘unique‘). Давайте рассмотрим полный список свойств класса Sprig_Field.

• $empty – поддерживает ли поле отсутствие значения. NOT NULL по сути. По умолчанию FALSE.
• $primary – является ли первичным ключем (PRIMARY KEY). По умолчанию FALSE.
• $unique – флаг уникальности (UNIQUE KEY). По умолчанию FALSE.
• $null – все пустые значения (например, пустые строки) автоматически будут преобразованы в NULL. По умолчанию FALSE.
• $editable – разрешено ли изменение даного поля пользователем. Может использоваться для автоинкрементых полей и автоматически генерируемых меток времени. По умолчанию TRUE.
• $default – значение по умолчанию.
• $choices – массив допустимых значений (что-то вроде эмуляции ENUM).
• $column – имя поля в БД. По умолчанию сгенерируется на основе имени объекта. Вы можете указать более удобный псевдоним для поля в методе _init(), а реальное имя указать в данном свойстве. Обычно это используется для внешних ключей.
• $description – описание поля.
• $in_db – существует ли поле в БД (такие поля в ORM помещались в $ignored_columns). По умолчанию TRUE.
• $label – метка поля. Используется для формирования элемента label формы, а также при валидации. По умолчанию сгенерируется автоматически, используя метод Inflector::humanize(), который заменяет тире и знаки подчеркивания на пробелы.
• $filters – массив применяемых фильтров валидации.
• $rules – массив правил для поля.
• $callbacks – массив внешних функций (коллбэков).

Немного в стороне стоят свойства $min_length и $max_length, которые могут быть добавлены в текстовые поля для ограничения длины.

Часто используемые комбинации данных свойств представлены в виде готовых классов-потомков Sprig_Field.

• Sprig_Field_Auto – автоинкремент. Первичный ключ, нередактируемый, пустые значения преобразовываются в NULL.
• Sprig_Field_Boolean – логическое поле. Может хранить NULL, значение по умолчанию – FALSE. При валидации автоматически применяется фильтр filter_var(FILTER_VALIDATE_BOOLEAN).
• Sprig_Field_Char – символьное поле. Можно указать минимальную/максимальную длину.
• Sprig_Field_Country – поле для кода стран в двухсимвольном (за небольшими исключениями) международном формате. Массив код => расшифровка хранится в свойстве $codes, которое будет скопировано в $choices по умолчанию. Если необходимо предоставить возможность ввода других кодов, установите свойство $prompt в TRUE.
• Sprig_Field_Email – поле для электронной почты, добавлено правило validate::email().
• Sprig_Field_Enum – поле, имеющее ограниченное число значений. Если Вы забудете их установить в свойстве $choices, получите Exception.
• Sprig_Field_Float – число с плавающей запятой. Можно настроить количество точек после запятой (свойство $places).
• Sprig_Field_Image – поле для хранения пути к изображению. При создании необходимо явно указать параметр ‘path‘ – путь к директории с картинками. Также можно передать длину и ширину (‘width‘ и ‘height‘).
• Sprig_Field_Integer – целочисленное значение. Можно задать ‘min_value‘ и ‘max_value‘.
• Sprig_Field_Password – поле для хранени паролей. Можно указать метод хэширования в свойстве ‘hash_with‘ (по умолчанию ‘sha1‘).
• Sprig_Field_Text – поле для многострочных текстовых полей.
• Sprig_Field_Timestamp – поле для хранения даты/времени. Поддерживаются свойства ‘auto_now_create‘ и ‘auto_now_update‘ (автоматическая подстановка значения NOW() при создании и редактировании соответственно, по умолчанию FALSE) и ‘format‘ (формат вывода данных на экран через функцию date(), по умолчанию ‘Y-m-d G:i:s A‘).
• Sprig_Field_ForeignKey – абстрактный класс, базовый для внешних ключей. NOT_NULL, но в то же время по умолчанию он не является существующим полем в БД (т.е. $in_db == FALSE). Дело в том, что не для всех типов связей внешний ключ располагается в текущей таблице (ниже рассмотрены доступные классы по типам связей).
• Sprig_Field_HasOne – класс для описания связи has_one (один-к-одному). Поле игнорируемое ($in_db == FALSE) и нередактируемое. Этот класс следует применять для “старшей” таблицы в связи, т.к. в той, которая экспортирует свой первичный ключ в связанную таблицу.
• Sprig_Field_BelongsTo – класс для belongs_to (обратная сторона связи has_one или has_many). В данном случае внешний ключ находится в таблице, так что $in_db == TRUE.
• Sprig_Field_HasMany – класс для has_many. Недоступен для редактирования.
• Sprig_Field_ManyToMany – поле HABTM. Может быть отредактировано, имеется дополнительное свойство $through (как Вы наверное догадываетесь, оно предназначено для имени промежуточной таблицы и по умолчанию формируется из названий связанных таблиц по тому же принципу, что и в ORM).

Кроме собственно полей, есть свойства для хранения мета-данных модели. По большей части они знакомы нам благодаря ORM:

• $_primary_key – имя поля для первичного ключа. Теоретически может быть массивом (в случае составного первичного ключа), но вроде как это еще не полностью поддерживаемая возможность.
• $_table – имя используемой таблицы.
• $_title_key – аналог $_primary_val из ORM. По умолчанию ‘name’.
• $_sorting – настройка сортировки по умолчанию. Синтаксис имя поля => направление, например array('created' => 'DESC').

Создание экземпляра модели и работа с ним

В отличие от ORM в Sprig конструктор недоступен для прямого вызова, создавать модели необходимо через статический метод factory($name, array $values = NULL). Это позволяет не создавать модель каждый раз заново, а использовать уже имеющуюся копию данного класса (эта копия представляет собой проинициализированную модель без каких-либо данных, т.е. происходит экономия на времени работы конструктора, в частности на методе _init()). При этом копии между собой не связаны, так что изменения в одной не повлекут корректировку другой.

Второй параметр $values позволяет передать значения для загрузки в модель. Значения, отсутствующие в списке полей таблицы, будут отброшены. Например, то, что в ORM записывалось как ORM::factory('blog', 1), в Sprig будет выглядеть как Sprig::factory('blog', array('id' => 1). Обратите внимание, что идентификатор будет загружен в модель, но запроса к БД не будет. Налицо все та же “ленивая загрузка”. Для явного обращения к БД надо использовать метод load().

Можно присваивать значения полям модели вручную, обращаясь к ним как в ORM, например $blog->id = 1. Также имеется метод values(array $values) для изменения сразу нескольких полей.

$blog->id вернет значение поля. Если необходим сам объект (в данном случае это Sprig_Field_Auto), используйте методы field($name) или fields().

CRUD

Метод load() я уже упомянул выше. Однако у него есть параметры, которые могут быть полезными для выборки данных из БД. Так, первым параметром идет объект класса Database_Query_Builder_Select, т.е. объект запроса на выборку, создаваемый обычно методом DB::select(). С его помощью можно указать дополнительные условия выборки. Второй параметр – $limit, позволяет ограничить количество отбираемых записей (по умолчанию 1).

Операции создания/редактирования и удаления в Sprig представлены отдельными методами (как мы помним, в ORM создание и редактирование были объединены в рамках метода save()).

• Метод create() создает новую запись в таблице, используя текущие значения. Если есть поле (или поля) типа Sprig_Field_Timestamp со свойством $auto_now_create == TRUE, то для него значением текущая метка времени. Далее автоматически будет вызвана валидация данных, так что вызовы метода create(), а также (забегаю вперед) и метода update(), должны заворачиваться в try ... catch(), но об этом ниже, в секции “Валидация”. Метод возвращает текущий объект ($this).
• Метод update() работает только с измененными данными (свойство $_changed). Кроме того, поля Sprig_Field_Timestamp со свойством $auto_now_update == TRUE будут заполнены текущей меткой времени. В целом все аналогично созданию записи – валидация измененных значений с дальнейшим сохранением в базе.
• Метод delete() предназначен для удаления записей, и может быть использован в различных случаях. Если запись была загружена из БД, она будет удалена. Если же объект только что создан и не сохранен в БД, введенные в него значения будут использованы в качестве условия для удаления всех подходящих записей в БД. Если модель пустая, ничего не будет удалено (интересно, как тогда удалить все записи, т.к. метода delete_all() нет).

Настройка формата значений при выводе на экран

Приятная “вкусность”. Для каждого поля можно менять форматирование значения, для чего используется метод verbose($value). По умолчанию он выводит значение как строку, но есть и отличные от дефолтных методы, например для меток времени и картинок:

// Sprig_Field_Timestamp, использует свойство $format для хранения формата даты
	public function verbose($value)
	{
		if (is_integer($value))
		{
			return date($this->format, $value);
		}
		else
		{
			return '';
		}
	}
 
// Sprig_Field_Image, выводит полный путь к картинке, используя свойство $path
	public function verbose($value)
	{
		return $this->path.$value;
	}

Есть и другие классы с собственными обработчиками (для чисел с плавающей запятой будет произведено форматирование через number_format(), для логических выведение строковых ‘TRUE‘ или ‘FALSE‘, а для Hasmany – вывод значений через запятую).

Работа с формами

Выбор элементов форм в зависимости от типа поля – одно из преимуществ Sprig. Каждый объект класса Sprig_Field должен реализовывать метод input($name, $value, array $attr = NULL). По умолчанию будет выведен либо текстовый элемент input, либо выпадающий список select (если задано свойство $choices):

	public function input($name, $value, array $attr = NULL)
	{
		// Make the value verbose
		$value = $this->verbose($value);
 
		if (is_array($this->choices))
		{
			return Form::select($name, $this->choices, $value, $attr);
		}
		else
		{
			return Form::input($name, $value, $attr);
		}
	}

Массив $attr позволяет передать дополнительные атрибуты элемента форм (например, ‘class‘ или ‘tabindex‘). Метод возвращает код сгенерированного поля формы. Как видно, метод input() активно использует verbose(), так что не забывайте его менять для создаваемых Вами классов нестандартных полей.

Для того, чтобы лучше понять, как (и зачем) реализовать собственный метод для формирования контролов, приведу методы для картинок и логических полей:

// Sprig_Field_Image
// Вывод поле для загрузки изображения. Если есть значение, то покажет и саму картинку
	public function input($name, $value, array $attr = NULL)
	{
		$input = Form::file($name, $attr);
 
		if ($this->value)
		{
			$input .= HTML::image($this->verbose());
		}
 
		return $input;
	}
 
// Sprig_Field_Boolean
// если установлено свойство $append_label, будет добавлен текст к checkbox'у
	public function input($name, $value, array $attr = NULL)
	{
		$checkbox = Form::checkbox($name, 1, $value, $attr);
		if ($this->append_label)
		{
			$checkbox .= ' '.$this->label;
		}
		return  $checkbox;
	}

Также есть метод inputs($labels), который позволяет разом получить массив контролов. Параметр $labels указывает, использовать ли в качестве ключей данного массива сгенерированный код для меток ($labels = TRUE, по умолчанию), либо просто имена полей. Например, так:

foreach ($blog->inputs() as $label => $input)
    echo $label."<br />".$input."<br />";

Валидация

Раз есть генерация форм, надо как-то обрабатывать введенные данные. Для этого есть возможность установки свойств валидации, кроме того не стоит забывать об автоматически добавляемых фильтров и правил валидации для отдельных стандартных классов (например, проверка корректности email для Sprig_Field_Email). Обратимся к все той же модели Sprig_Model_User, так там объявлено поле `username` в методе _init():

	'username' => new Sprig_Field_Char(array(
		'empty'  => FALSE,
		'unique' => TRUE,
		'rules'  => array(
			'regex' => array('/^[\pL_.-]+$/ui')
		),

Поскольку внутри используется стандартный класс Validate, синтаксис объявления свойств привычен. Сама проверка запускается методом check(array $data = NULL). Да, в Sprig можно (напрямую) передать в модель данные для валидации (тот же массив $_POST), однако это немного другой механизм, отличный от валидации в ORM версии 2.3.4. Во время валидации сама модель не меняется, она предоставляет данные для создания объекта Validate (т.е. свойства $label, $filters, $rules и $callbacks соответствующих полей).

Если параметр $data не указан, будут проверяться измененные (и несохраненные) данные модели. Таким образом, проверять только что загруженный из БД объект бессмысленно.

Метод check() возвращает массив обработанные данные в случае успеха (они могут отличаться от исходных, например из-за фильтрации). А вот если выявлено несоответствие, будет сгенерировано исключение Validate_Exception, так что придется оборачивать вызовы check() в блоки try ... catch:

try
    {
        $object->check();
    }
    catch (Validate_Exception $e)
    {
        $errors = $e->array->errors('validation');
    }

Объект Validate_Exception содержит свойство $array, в которое помещаются данные при генерации исключения. В данном случае это сам объект Validate, так что $e->array->errors() осуществляет запрос ошибок валидации.

Прочие полезные методы

• Получить значения объекта как массив можно с помощью метода as_array($verbose), где параметр $verbose определяет, применять ли метод verbose() на все поля, либо отдавать как есть (по умолчанию).
• Проверить, менялось ли какое либо поле или значения модели в целом с момента последнего сохранения или загрузки, можно через метод changed($field). Если параметр $field не указан, вернется массив измененных полей (имя поля => значение), иначе – логическое TRUE (поле поменялось) или FALSE.
• Метод loaded() полезен для проверки, был ли объект загружен из БД или он просто создан “на лету”.
• Метод pk($table) возвращает имя поля для первичного ключа. Если параметр $table указан, то он будет подставлен перед именем поля в качестве названия таблицы (значение TRUE используется для подстановки имени текущей таблицы модели). Также есть метод tk($table), который возвращает т.н. “титульный” ключ, т.е. значение свойства $_title_key.
• Для формирования выпадающих списков есть знакомый нам метод select_list($key = NULL, $value = NULL). Он возвращает массив $key => $value всех записей в БД.
• Метод table() возвращает имя таблицы модели.

Напоследок

• Я нашел зачатки поддержки составных первичных ключей (свойство $_primary_key может быть массивом полей), но пока это не везде работает. Возможно, в следующих коммитах ситуация прояснится.
• Также не увидел как использовать напрямую методы Database_Query_Builder, например limit() или where(). Возможно, они появятся позже. Единственный доступный способ – передача параметра $query (в котором можно настроить большинство необходимых условий) в метод load().

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