CRUD

Помимо метода save() теперь есть отдельные методы create() и update() для добавления новой или обновления старой записи соответственно. Метод save() просто запускает create() или update() в зависимости от $this->loaded().

Фильтры

Как мы помним, ранее валидация в ORM держалась на трех китах – фильтры, правила и коллбэки. После всех тех изменений в ветке 3.1 валидация сводится к использованию правил. Но фильтры остались, изменилась их роль в модели. Я уже писал, что разработчики Kohana считают правильным подгонять данные модели под нужный формат на этапе присвоения значения, а не в момент валидации. И вот результат – в ORM v3.1 появилась возможность применять различного рода преобразования перед сохранением значения в поле модели.

Вот как это примерно может выглядеть:

public function filters() 
{
   return array(
      TRUE        => array(
         array('trim'),
      ),
      'username'  => array(
         array('strtolower'),
      ),
      'login_count' => array(
        array('intval'),
      ),
   );
}

Теперь фильтры указываются не в свойстве $_filters, а в методе filters(), который должен возвращать массив. Ключами массива являются либо имена полей, либо TRUE (т.е. фильтр действует на все поля). Каждому ключу соответствует массив фильтров, фильтры тоже представляют собой массивы вида (фильтр, параметры). В приведенных выше примерах явно указаны только имена фильтров (стандартные функции php), они достаточно просты. Но роль фильтров может быть значительно расширена засчет все тех же контекстов, введенных в валидации Kohana v3.1. Давайте представим, что у нас текстовое поле text, которое не должно содержать более 100 символов:

public function filters() 
{
   return array(
      'text'   => array(
         array('text::limit_chars', array(':value', 100, ''))
      ),
   );      
}

Вуаля! При установке значения будет вызван метод text::limit_chars(), который обрежет значение до 100 символов. Строка ‘:value‘, конечно же, является контекстом, который будет заменен на фильтруемое значение. Третьим параметром я передаю пустую строку, т.к. по умолчанию добавится символ “многоточие”.

В качестве контекстов можно использовать не только ‘:value‘, но также ‘:model‘ (текущая модель) и ‘:field‘ (имя поля, к которому относится фильтр).

Пример выше можно расширить еще больше. Представим, что у нас есть поля text и intro, причем intro является укороченной версией значения из text и мы не хотим заполнять его в явном виде. Создадим фильтр, который будет при заполнении поля text вычислять значение и для intro:

public function filters() 
{
   return array(
      'text'   => array(
         array(array($this, 'set_intro'))
      ),
   );      
}
 
public function set_intro($value)
{
   $this->intro = text::limit_chars($value, 100, '');
   return $value;
}

Не забудьте вернуть значение $value, это обязательное требование для фильтров!

Все просто – фильтр вызывает метод set_info() для текущего объекта модели, а тот заполняет вычисляемое поле intro. Получаем что-то вроде Jelly_Field_Expression из Jelly.

Метки (labels)

Тут изменение достаточно простое – как и в случае с фильтрами, вместо свойства $_labels надо создавать метод labels():

public function labels()
{
   return array(
      'text'   => 'article text',
   );
}

Валидация

Из валидации убраны фильтры, коллбэки и правила теперь по сути одно и то же. Достигается это за счет использования все тех же контекстов валидации, создавать сложные функции для проверки полей модели. В качестве контекстов доступны ‘:field‘, ‘:value‘, ‘:validation‘ (имя поля, его значение и сам объект Validation – эти контексты устанавливаются классом Validation) и ‘:model‘ (текущая модель ORM). В общем, возможности для валидации весьма широки, и грустить об отказе от коллбэков в их изначальном виде не приходится.

Объявляются правила в методе rules():

public function rules()
{
   return array(
      'username'   => array(
         array('not_empty'),
         array('min_length', array(':value', 4)),
         array(array($this, 'is_unique'), array(':value', ':validation')),
      ),
   );
}

Первое правило просто проверяет поле ‘username‘ на наличие значения. Обратите внимание, что стандартные правила класса Valid можно указывать просто по имени, а не как ‘Valid::not_empty‘ или array('Valid', 'not_empty'). Параметры в данное правило оставляем пустые, в этом случае автоматически будет передавать проверяемое значение (т.е. контекст ‘:value‘). Второе правило проверяет на минимальную длину, и тут уже мы передаем два параметра – значение и минимальное число символов. Третий параметр по сути является коллбэком, это вызов метода is_unique() с передачей в него значения и объекта Validation.

Объект Validation нужен для передачи в него текста ошибки, если вдруг коллбэк обнаружит расхождения. Выглядеть это будет примерно так:

public function is_unique($value, $validation)
{
   if ( ! условие на уникальность)
   {
      $validation->error('username', 'username is not unique');
   }
}

Чтобы метод is_unique() был более универсальным, в него можно дополнительно передавать контекст ‘:field‘ и писать ошибку с его использованием. Например, можно будет проверять не только username, но и email – механизм проверки в принципе ничем не отличается.

Проверка модели

Вызов валидации осуществляется все тем же методом check(). Но теперь метод возвращает не TRUE/FALSE, а бросает исключение ORM_Validation_Exception, если найдены ошибки (прямо как в Jelly). Соответственно теперь каждая проверка должна быть заключена в блок try...catch():

try {
   $user->save();
}
catch(ORM_Validation_Exception $e)
{
   // произошла ошибка валидации
}

Да-да, из приведенного мной участка кода следует, что метод check() автоматически вызывается при сохранении модели методами save(), create() и update().

Работа над ошибками валидации

Если раньше мы могли получить ошибки через встроенный объект Validate модели ORM (конструкцией вида $user->validate()->errors()), то теперь для этого надо использовать бросаемое исключение. Для этого в классе ORM_Validation_Exception существует метод errors():

try {
   $user->save();
}
catch(ORM_Validation_Exception $e)
{
   $errors = $e->errors('validation');
}

Принцип такой же – передаем в метод errors() путь к переводу в messages, а также булевский файл, переводить ли результат через i18n. Замечу, что можно использовать и $user->validation()->errors('validation') – этот метод тоже вернет тексты ошибок. Тогда в чем же разница? Об этом – следующий пункт различий.

Внешняя валидация

На форумах часто спрашивают, как проверить данные для нескольких моделей, либо данные для модели + капчу. Раньше эта задача полностью ложилась на плечи разработчика проекта, но сейчас ORM предлагает свое решение. В методы check(), save(), create() и update() можно передавать дополнительный объект класса Validation, который уже должен быть подготовлен к проверке (т.е. иметь загруженные входящие данные, правила и т.д.).

Перед проверкой самой модели метод дополнительно проверяется этот дополнительный объект Validation (если передан), и результат его проверки влияет на общий итог валидации модели. Ошибки будут добавлены в бросаемое исключение, поэтому и рекомендуется извлечение ошибок через объект ORM_Validation_Exception – он просто обладает информацией о внешних ошибках.

Таким образом, валидация будет провалена даже если сама модель заполнена корректно, но, к примеру, капча неверна.

В связи с возможным наличием “посторонних” ошибок, генерация ошибок несколько усложняется. Теперь массив ошибок (до перевода, его можно получить методом errors() без параметров) помимо ошибок самих полей модели содержит массив ошибок внешней валидации под индексом ‘_external‘. А сам механизм перевода ошибок выглядит так:

• Вызываем метод errors($directory, $translate) исключения ORM_Validation_Exception, передавая туда в качестве первого параметра имя директории с переводом. Если не хотите брать перевод непосредственно из папки messages, то передайте пустую строку.
• Внутри исключения происходит поиск файлов с переводом, учитывая переданный параметр $directory. Предположим, передали $directory = 'valid'. Для валидации полей модели Model_User будет ожидаться имя файла messages/valid/user.php (где ‘user‘ – имя модели, хранимое в свойстве $_object_name), если он не найден, то перевод берется из файла messages/validation.php.
• Для ошибок внешней валидации будет вычислен путь messages/valid/user/_external.php. Опять же, если такой файл не найден (или в нем нет нужного перевода), идем к дефолтному messages/validation.php.

Решение достаточно интересное. С одной стороны, мы можем предусмотреть custom‘ные внешние ошибки для каждой модели, используя файлы _external.php, а с другой – всегда можно положиться на старый добрый messages/validation.php, в котором уже прописаны все стандартные тексты.

Прочие отличия от 3.0

• Добавлено свойство $_db_group. Оно выполняет функции свойства $_db из ветки 3.0, т.е. содержит имя профиля Database для данной модели. Таким образом, при портировании своих моделей из 3.0 в 3.1 надо помнить об этом изменении, иначе модели будут использовать дефолтную конфигурацию.
• Метод add($alias, $far_keys), который позволяет добавлять связь HABTM, в версии 3.1 поддерживает большое число форматов для параметра $far_keys – это может конкретная модель ORM (единственный вариант, доступный в 3.0), ее первичный ключ, или даже массив ключей (для добавления сразу нескольких связей). Зато исчезла возможность передать дополнительные значения в промежуточную таблицу, вероятно как раз из-за возможного добавления нескольких записей.
• Метод remove($alias, $far_keys) работает по тому же принципу – можно передать один или несколько идентификаторов, а если параметр $far_keys пустой, то удалятся все имеющиеся записи для данной связи.
• В метод values($values, $expected) добавлен второй параметр – список ключей загружаемого массива, которые надо учитывать. Бывает удобно, когда в качестве массива $values выступает $_POST или $_GET. Кстати, хотя в комментариях к этому методу написано, что он поддерживает загрузку данных для связи 1-к-1 (has_one и belongs_to), реализации данного функционала я не нашел. Шажок назад по сравнению с 3.0.
• Класс ORM реализовывает интерфейс serializable, в соответствии с которым добавлены методы serialize() и unserialize(). Напомню, что в 3.0 использовались “магические” __sleep() и __wakeup().
• Добавлены PhpDoc-комментарии, описывающие методы объектов Query Builder (например where() или from()) и “магические” методы модели, возвращающие соответствующие защищенные свойства (например, знаете ли вы, что $user->has_many() вернет значение свойства $_has_many?). Правда, в случае с магическими методами IDE правильно подсказывать не будет, т.к. методы почему-то описаны как свойства (т.е. с использованием @property вместо @method).

В заключение скажу, что изменения достаточно интересные, правда слегка однобокие (все ушло в валидацию). Лично я все жду, когда в ORM добавятся алиасы для полей, как в Jelly.

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

Базовые изменения

• Имена полей теперь должны начинаться с префикса Jelly_, т.е. если раньше было Field_BelongsTo, то теперь надо писать Jelly_Field_BelongsTo. Вполне логично, резко уменьшаем вероятность коллизий с другими подключаемыми модулями.
• Метода Jelly::select() теперь нет. Его задачи разделены между Jelly::factory() и новым методом Jelly::query(). Первый теперь отвечает за создание пустой модели, плюс имеется возможность передать туда ключ для непосредственной загрузки нужной записи. Тут все стало как в ORM. Для всех остальных действий, связанных с записями в БД, используется Jelly::query(). Он возвращает объект типа Jelly_Builder.
  Например, можно удалить несколько записей с учетом примененных условий:
  

  // дело происходит внутри модели, поэтому передаем $this
  // а можно передать имя модели к примеру
  Jelly::query($this)
          ->where('expires', '<', time())
          ->delete();

  Впрочем, многие наверняка захотят заменить вызов ->where(…) на более элегантное ->expired(), используя расширение объекта Jelly_Builder.

События и Поведения (Events & Behaviors)

Ага, теперь есть набор заранее определенных событий, возникающих при стандартных действиях (сохранение записей, инициализация моделей и т.д.). Полный список на данный момент такой:

• builder.call_<метод>
• builder.before_select
• builder.after_select
• builder.before_insert
• builder.after_insert
• builder.before_update
• builder.after_update
• builder.before_delete
• builder.after_delete
• meta.before_finalize
• meta.after_finalize
• model.call_<метод>
• model.before_validate
• model.after_validate
• model.before_save
• model.after_save
• model.before_delete
• model.after_delete

Имя события состоит из объекта-инициатора (модель, Jelly_Builder, Jelly_Meta) и собственно описания этого события (как правило это префикс before_ или after_, и само событие). Чтобы обрабатывать эти события, используется еще одно понятие – поведение модели (behavior), реализовываемое классом Jelly_Behavior.

Сперва создается собственно класс, описывающий поведение модели. Например, для Model_User он будет называться Model_User_Behavior (на самом деле имя может быть практически любое):

class Model_User_Behavior extends Jelly_Behavior {
 
	public function model_before_save($user, $event)
	{
             // тут делаем свои проверки, можно писать логи и т.д.
	}
}

Имя метода зависит от имени нужного события (просто заменяем точку на подчеркивание). Параметры тоже могут различаться. Но первый – обязательно сама модель, а последний – событие (точнее, не Jelly_Event, а Jelly_Event_Data). Модель нам нужна для получения “пациента”, а событие – для обратной связи (влияние на работу самого события и инициировавшего его процесса).

Если что-то нас не устраивает (данные в модели не подходят для сохранения), устанавливаем параметр $event->return в FALSE, а $event->stop в TRUE. Свойство return содержит результат работы события (успешным считается любое не-FALSE значение), а stop означает, что дальше это событие отрабатываться не будет (да-да, можно вешать несколько обработчиков-поведений на одну модель).

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

Подключать обработчики надо, естественно, в методе initialize($meta):

$meta->behaviors(array(
   'user'  => new Model_User_Behavior, 
));

Ветка behaviors развивалась еще весной, но сейчас там код, сильно отличающийся от unstable, поэтому я его отбросил. Хотя там были интересные реализации, например SoftDelete для “мягкого” удаления записей в БД.

Поведения довольно удобная штука, например я за полчаса добавил возможности MPTT из старой своей библиотеки через них. Собственно, разработчики модуля в планах ставят создание поведений для MPTT и ClosureTable (такой способ хранения данных, когда все дерево хранится отдельно в виде пары предок-узел, полностью описывающих всех предков узла до самого корня).

Изменения в валидации

Валидация в модели теперь осуществляется своими силами. В модуле появился целый набор классов: Jelly_Validator, Jelly_Validator_Rule, Jelly_Validator_Callback и Jelly_Validator_Filter. Соответственно валидация осуществляется методом validate(), а сам валидатор получить можно через validator($data), где $data – необязательный массив данных для проверки (по умолчанию данные берутся из модели).

Появилось понятие “контекст” – это что-то вроде псевдонима для объекта или какого-то значения. Например, при создании модели автоматически создается контекст ‘:key‘, содержащий значение ключа, и ‘:model‘, содержащий ссылку на текущую модель. Вот пример того, как можно использовать контекст :model:

// поле test, к которому мы хотим добавить callback
'test'   => new Jelly_Field_String(
   'callbacks' => array(
         array(array(':model', 'test'), array(':validate', ':callback', ':field', ':value')),
   )
),

Теперь при валидации поля будет осуществлен вызов метода test() текущей модели (контекст :model) и туда будут переданы объект Jelly_Validator (контекст :validate), текущий объект Jelly_Validator_Callback (:callback), название проверяемого поля и его значение поля (контексты :field и :value). Эти контексты создаются автоматически при проверке каждого поля. Ну и конечно же, можно задавать свои контексты, используя методы context() и contexts() валидатора модели.

Прочие мелочи

Добавился класс Jelly_Field_Image. Помимо просто загрузки и сохранения изображения он позволяет сразу создавать превьюшки (указываются в параметрах поля). Можете почитать вот тут поподробнее.
В Jelly_Builder‘е появился метод key($value), который является сокращением от ->where($this->unique_key($value), '=', $value), т.е. позволяет быстро добавить условие по ключу. Удобно.
Также там добавился метод type($type). С его помощью можно на лету менять тип запроса (Database::SELECT, Database::INSERT и т.д.).

В моделях появлась возможность сбросить все изменения (вернуться к первоначально загруженному состоянию), с помощью метода revert().

Неразобранное

• Встречал в нескольких местах упоминание поля Jelly_Field_Polymorphic и некоего ключа polymorphic_key. Но вроде бы это все еще не реализовано, работы судя по всему велись/ведутся ветке Polymorphic. Либо часть реализации будет лежать на плечах пользователей модуля (?).
• Скорее всего для этих же целей вводится понятие “дочерних” моделей (children). Класс Jelly_Meta позволяет устанавливать и получать дочерние модели (названия классов) через метод children(). При этом поля, являющиеся Jelly_Field_Polymorphic (они по идее и должны содержать имена моделей), автоматически
  добавляют свои значение в свойство $_children.

Процесс идет…

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

Вступление

В качестве подопытного выступает модель Model_User, которую мы будем постепенно связывать с другими моделями. Настройку будем вести от простого к сложному, в начале у нас все по умолчанию. По мере освоения материала будем усложнять задачу нестандартными именами полей и связей. Вся работа происходит в статическом методе initialize(Jelly_Meta $meta), в котором описываются все специфические свойства модели. Прочитайте предыдущую статью, если не помните, как инициализируются модели в Jelly. Поля связей принципиально ничего не отличаются, только свойства (параметры для конструктора) в них немного другие.

Связь типа “Один-ко-многим” (HasMany)

Пусть имеется модель Model_User, с которой ассоциируются статьи (один пользователь может иметь несколько статей).

Короткая форма:

   'articles' => new Field_HasMany

В результате будет автоматически вычислено, что на другом конце связи находится модель Model_Article, внешний ключ – user_id.

Расширенная форма:

   'articles' => new Field_HasMany(array(
      'foreign'   => 'article.user_id'
   ))

Здесь мы уже описали имена модели и внешнего ключа, разделив их точкой. Можно укоротить запись:

   'articles' => new Field_HasMany(array(
      'foreign'   => 'article'
   ))

Опустив имя внешнего ключа, мы подразумеваем автоматическое вычисление его имени. В общем, это эквивалентно записи

   'articles' => new Field_HasMany(array(
      'foreign'   => 'article.user:foreign_key'
   ))

Jelly возьмет настройки модели Model_User для извлечения имени внешнего ключа. По умолчанию это имя модели + ‘_id’ (как и в ORM).

Изменить имя внешнего ключа для модели можно с помощью метода foreign_key(), например foreign_key('user_key').

Связь типа “Один-к-одному” (HasOne)

По сути это частный случай связи HasMany, и синтаксис такой же.

Связь типа “Много-к-одному” (BelongsTo)

Главное отличие (в плане структуры таблицы) от HasMany в том, что внешний ключ расположен в данной модели. Для связи пользователь-статьи это означает, что внешний ключ расположен в модели Model_Article, и участвует в определении связи. Соответственно короткая запись:

   'user' => new Field_BelongsTo

означает, что при обращении к $article->user произойдет попытка загрузить модель Model_User по значению ключа user_id в модели Model_Article.
Если предположить, что связь должна называться ‘author‘, а внешний ключ называется author_id и ссылается на первичный ключ id в модели Model_User, то получится такое объявление:

   'author' => new Field_BelongsTo(array(
      'foreign'  => 'user.id',
      'column'  => 'author_id',
   ))

Свойство foreign содержит все, что касается связанной модели (имя и внешний ключ), а column – имя поля в данной модели. Думаю, всем понятно, почему column отсутствует в связях HasMany и HasOne Если значение для column не указано, оно генерируется на основании указанного имени модели с прибавкой суффикса ‘_id‘, т.е. user_id в данном случае. Обратите внимание, что используется не имя связи, а имя модели!

Конечно, для свойства foreign можно (и нужно – это более гибкая запись) использовать ‘user.:primary_key‘ или просто ‘user‘.

Связь “Много-ко-многим” (ManyToMany)

Этот тип связи характеризуется выносом внешних ключей обеих связанных моделей в промежуточную таблицу (как правило, эта таблица только из этих ключей и состоит). Пусть это будет извечное пользователи-роли с промежуточной таблицей roles_users.
Короткая запись:

   'role' => new Field_ManyToMany

В результате связь будет основана на предположении, что на другом конце находится модель Model_Role, а промежуточная таблица roles_users содержит ключи user_id и role_id. Имя промежуточной модели формируется по такому же принципу, что в ORM.

Предположим, что роли находятся в таблице rolez (а модель все та же – Model_Role) с первичным ключом role_id, промежуточная таблица users_roles, а внешние ключи называются user_key и role_key. В таком случае надо использовать полную запись связи:

   'rolez' => new Field_ManyToMany(array(
      'foreign'  => 'role.role_id',
      'through'  => array(
         'model'     => 'users_roles',
         'columns'  => array(
             'user_key',
             'role_key'
         )
      ),
   ))

Итак, если свойство foreign нам уже знакомо (обозначаем настройки для связи с моделью Model_Role, как в HasMany), то свойство through в новинку. Это массив, который в наиболее полном варианте должен содержать ключи ‘model‘ (имя промежуточной модели или таблицы) и ‘columns‘ (имена внешних ключей для промежуточной таблицы). Порядок перечисления внешних ключей важен – сперва идет имя внешнего ключа от текущей модели (т.е. при объявлении связи в модели Model_Role мы бы их поменяли местами).
Есть и упрощенный вариант – указать только имя промежуточной модели/таблицы:

   'rolez' => new Field_ManyToMany(array(
      'foreign'  => 'role.role_id',
      'through'  => 'users_roles'
   ))

В этом случае внешние ключи будут вычислены как user.:primary_key и role.:primary_key.

Заключение

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

class Model_User extends Jelly_Model
{
   public static function initialize(Jelly_Meta $meta)
   {
      $meta->name_key('username')
         ->sorting(array('username' => 'ASC'))
         ->fields(array(
            'id' => new Field_Primary,
            'username' => new Field_String(array(
               'unique' => TRUE
            )),
            'password' => new Field_Password,
            'email' => new Field_Email(array(
               'unique' => TRUE
            )),
         // user has many articles
            'articles' => new Field_HasMany(array(
               'foreign'   => 'article.user_id'
            )),
         // user has one profile
            'profile'  => new Field_HasOne(array(
               'foreign'  => 'user_profile'
            )),
         // user has and belongs to many roles
            'roles' => new Field_ManyToMany(array(
               'foreign'  => 'role',
               'through'  => array(
                  'model'     => 'users_roles',
                  'columns'  => array(
                     'user_id',
                     'role_id'
                  ),
               ),
            )),
            'group'    => new Field_BelongsTo(array(
               'foreign'   => 'user_group',
               'column'   => 'group_id'
            )),
         ))->foreign_key('user_id');
    } 
}

Думаю, тут все понятно

Вступление

Для начала вспомним, как мы описываем свойства модели:

class Model_Auth_User extends Jelly_Model
{
	public static function initialize(Jelly_Meta $meta)
        {
		$meta->name_key('username')
			->sorting(array('username' => 'ASC'))
			->fields(array(
			'id' => new Field_Primary,
			'username' => new Field_String(array(
				'unique' => TRUE,
				'rules' => array(
						'not_empty' => NULL,
						'max_length' => array(32),
						'min_length' => array(3),
						'regex' => array('/^[\pL_.-]+$/ui')
					)
				)),
			'password' => new Field_Password(array(
				'hash_with' => array(Auth::instance(), 'hash_password'),
				'rules' => array(
					'not_empty' => NULL,
					'max_length' => array(50),
					'min_length' => array(6)
				)
			)),
			'password_confirm' => new Field_Password(array(
				'in_db' => FALSE,
				'callbacks' => array(
					'matches' => array('Model_Auth_User', '_check_password_matches')
				),
				'rules' => array(
					'not_empty' => NULL,
					'max_length' => array(50),
					'min_length' => array(6)
				)
			)),
			'email' => new Field_Email(array(
				'unique' => TRUE
			)),
			'logins' => new Field_Integer(array(
				'default' => 0
			)),
			'last_login' => new Field_Timestamp,
			'tokens' => new Field_HasMany(array(
				'foreign' => 'user_token'
			)),
			'roles' => new Field_ManyToMany
		));
    }
}

Все происходит в статическом методе initialize(), где мы должны сохранить информацию о связанной с моделью таблице (имя таблицы, имена полей, связи). Для разных типов полей есть предопределенные классы, у каждого из них могут быть свои особенности в настройке и работе. Так как более-менее адекватного руководства я не нашел (плохо искал?), на свет появилась данная статья.

Общие свойства полей (класс Field_Core)

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

• column – имя поля в БД. Обычно совпадает с именем поля в модели, но это необязательно.
  

  Если при создании поля в конструктор передавать строковое значение, а не массив (т.е. new Field_Primary('myid')), то это значение будет расцениваться как переданное значение свойства column.

• primary – флаг первичного ключа (FALSE по умолчанию). Обычно явно не указывается, достаточно для нужного поля установить тип Field_Primary (первичный ключ).
• unique – флаг уникальности поля (FALSE по умолчанию). Автоматически выставляется в TRUE для полей Field_Primary. Добавление этого флага означает, что при валидации модели для данного поля будет применен дополнительный callback _is_unique(). Фактически это приводит к дополнительному запросу БД.
• in_db – флаг наличия в БД (TRUE по умолчанию). Если установить FALSE, получим аналог ignored_columns из ORM.
• default – значение по умолчанию для поля (изначально NULL).
• null – конвертировать или нет пустые (empty()) значения в NULL. По умолчанию FALSE.

Кроме этих свойств есть еще несколько, не относящихся к СУБД, но важных при описании полей.

• description – описание поля. Оно напрямую нигде не используется, но может быть использовано, скажем, при построении форм (для расширенной подсказки о назначении поля). По умолчанию содержит пустую строку.
• name – имя поля для генерации элемента формы (т.е. HTML-атрибут name).
• label – имя поля в более удобном и понятном человеку формате, чем name. Обычно используется для тэгов LABEL формы. Если не указано явно, примет значение свойства column, обработанное методом inflector::humanize().
• filters, rules, callbacks – эти три свойства используются для валидации полей. Там все стандартно, как и в ORM.

Логические поля (Field_Boolean)

Вроде бы тут все ясно – либо ДА, либо НЕТ. Но разработчики предпочли гибкость, в результате даже в таком простом поле есть что понастраивать:

• true – значение, которое надо записывать в БД при положительном значении поля (масло масляное, ага). По умолчанию 1.
• label_true – описание положительного значения (по умолчанию “Yes“). Может быть использовано при выводе значения на экран или для генерации формы.
• false – аналогично свойству true, только действует для отрицательного значения поля. По умолчанию, естественно, равно 0.
• label_false – как вы уже наверняка догадались, метка для свойства false. По умолчанию “No“.

Скорее всего вы эти свойства менять и не будете. Но сама возможность не может не радовать.

Метка времени (Field_Timestamp)

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

• format – формат метки времени, в котором значение должно храниться в БД. Синтаксис можно посмотреть в описании функции date(). NULL по умолчанию, т.е. никакого преобразования не происходит.
• pretty_format – формат метки времени, предназначенный для человеческих глаз. Данный формат используется при генерации элемента формы стандартным шаблоном Jelly. Согласитесь, не каждого обрадует значение ‘2010-09-09‘. Синтаксис аналогичен свойству format. Значение по умолчанию ‘r’ (дата в формате RFC 2822, например ‘Thu, 09 Sep 2010 12:00:00 +0300′).
• auto_now_create – флаг, отвечающий за автоматическое заполнение поля текущей меткой времени при первоначальном сохранении (т.е. при создании записи). По умолчанию FALSE.
• auto_now_update – аналогично auto_now_create, но действует при обновлении записи. По умолчанию FALSE.

Несмотря на все форматы, сама метка времени в поле хранится в виде целого числа (UNIX timestamp), т.е. можно не напрягать голову мыслями о текущем формате времени.

Числа с плавающей запятой (Field_Float)

Данный класс располагает специальным свойство places, который определяет количество знаков после запятой в итоговом числе. Если данное свойство отлично от NULL и является числом (is_numeric()), то значение будет округлено до places знаков.

Стоит обратить внимание, что отрицательные и дробные значения тоже являются числами, и вполне могут быть использованы в данном свойстве. Например, если установить places = 2.3, то значение будет округлено до двух знаков после запятой (дробная часть отбрасывается). Если же значение отрицательное, то округлять будут целую часть числа, например при places = -2.3 число 12345.6789 будет сохранено в базу как 12300. Это может быть полезно при форматировании дробных чисел.

Строковые и целочисленные поля (Field_String, Field_Text, Field_Integer)

Тут все без каких-либо особенностей, просто значение явно преобразовывается в нужный тип (строковый и числовой соответственно).

На данный момент я не нашел различий между Field_String и Field_Text в части реализации. В комментариях написано, что Field_Text предназначен для работы с большими текстами, возможно это еще в @TODO.

Поле ограниченного выбора (Field_Enum)

Данное поле предназначено для работы с неким заранее известным диапазоном значений. Например, это может быть пол (мужской/женский/не указан) или месяц года. Сами значения для выбора указываются в свойстве choices в виде массива. Можно использовать стандартный массив вида array('male', 'female', 'unknown'), а можно использовать осмысленные значения для ключей: array('1' => 'male', 2 => 'female', 0 => 'unknown'). Это удобно при генерации списков выбора (select list), когда пользователю показывается текстовое описание, за которым скрывается конкретный идентификатор значения в БД.

Если указанное пользователем значение в списке choices отсутствует, то оно будет заменено значением из default.

Вычисляемое поле (Field_Expression)

Очень интересный тип данных. Он позволяет перекладывать на СУБД функции вычисления каких-либо значений на основе полученных из таблицы данных. Например, у нас есть поле `birthday` (дата рождения). Чтобы получить возраст пользователя, создаем вычисляемое поле:

'age'   => new Field_Expression(array(
      'column' => DB::expr('(YEAR(CURRENT_DATE)-YEAR(birthday)) - (RIGHT(CURRENT_DATE,5)<RIGHT(birthday,5))')
      )),

В результате запрос к БД на выборку данных из таблицы будет содержать дополнительное поле ‘age‘, заполняемое содержимым нашего выражения. Так как поле физически в таблице не существует, параметр in_db автоматически устанавливается в FALSE.

Точнее, должно было содержать, по задумке авторов. На самом деле у меня Field_Expression не заработал, пока я не внес кое-какие поправки в класс Jelly_Meta_Core. Тикет создан, жду реакцию разработчиков.

Поле для хранения пароля (Field_Password)

Пароль по сути ничем не отличается от обычного строкового поля (поэтому Field_Password extends Field_String), за исключением уже привычной нам традиции шифровать значение при сохранении модели. Единственная доступная нам опция – свойство hash_with, которое содержит имя функции для шифрования (по умолчанию “sha1” – указывать без скобочек!).

Slug-поле (Field_Slug)

Долго ломал голову, как же по-русски назвать этот термин, ничего не придумал Slug – это такое нормализованная строка, где могут быть использованы только маленькие латинские буквы, дефисы и слэши (я привел мнение разработчиков Jelly). Все остальное заменяется на дефисы. Например, строка ‘Hello, World!‘ будет автоматом преобразована в ‘hello-world‘. Никаких свойств нет, хотя в принципе напрашивается как минимум возможность установки собственного диапазона допустимых символов.

Поле адреса электронной почты (Field_Email)

Обычное текстовое (Field_Text) поле, только автоматически будет применяться правило Validate::email() при сохранении.

Прячем объекты и массивы (Field_Serialized)

Данное поле позволяет работать с сериализованными (serialized) переменными. Зачем это надо? Бывает удобно хранить массивы или целые объекты в БД (например, конфигурация ACL или прочие структуры в том же духе). При заполнении значения происходит попытка восстановить (unserialize) объект, а при сохранении записи в БД – обратная запаковка (сериализация). Единственный минус (и то, возможно, только мне так кажется) – вызовы serialize() и unserialize() предваряются “собачкой” для подавления ошибок.

Загрузка файлов (Field_File)

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

• path – путь к директории для сохранения. Естественно, директория должна быть доступна для записи. Это обязательное поле, у которого нет значения по умолчанию.
• delete_old_file – данный флаг используется при замене одного файла другим. Если TRUE (а это значение по умолчанию), то при удачной загрузке новый файл заменит старый не только в БД, но и на диске (т.е. старый файл будет удален физически).

Сам по себе файл лежит на диске, а в поле хранится его имя. Таким образом, доступ к файлу можно получить через $this->path.$this->value.

Пора заканчивать

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

1. Есть модель ORM, в конструкторе который Вы изменяете важные параметры, например $_table_name.
2. Объекты модели хранятся в сессии.

Ошибка

Как правило, Database_Exception – те самые важные параметры модели почему-то не переопределены. Хотя Вы их точно в конструкторе прописывали!

В чем дело?

Проблема возникнет, когда Kohana будет извлекать модель из сессии (точнее при создании объекта Session). Дело в том, что модель хранится в сериализованном виде, при десериализации (распаковывании) объекта ORM конструктор не вызывается. Так что все Ваши модификации будут пропущены (если говорить про параметр $_table_name, то модель будет обращаться к не той таблице БД).

Чтобы этого избегать, следует использовать protected-метод _initialize(). Он вызывается из конструктора, там по умолчанию происходят все вычисления дефолтовых значений для $_table_name, $_db, свойств связей и т.д. Как раз-таки с этого метода начинается десериализация модели ORM, так что все модификации складываем именно в _initialize(). Например, так:

protected function _initialize()
{
    if (empty($this->_table_name) AND ($table_name = Kohana::config('models')->table))
    {
        $this->_table_name = $table_name;
    }
 
    parent::_initialize();
}

Такое может возникнуть, когда свойства модели заполняются в зависимости от каких-либо условий (параметр Kohana::$environment или по настройкам конфигов). Раньше я всегда использовал конструктор, теперь вот есть смысл выносить все это в _initialize(). Да, случается нечасто (не так уж много случаев, когда объект ORM хранится в сессии целиком), но может стать причиной долгих поисков. В общем, я Вас предупредил

Итак, скачиваем модуль и начинаем исследование содержимого. Для начала отмечу, что в составе модуля поставляется документация в формате “родного” Userguide. То есть если в проекте подключены модули Jelly и Userguide, то в секции Modules документации появится соответствующий раздел Jelly. В документации присутствует и русский перевод (спасибо тебе, Сергей avis Гладковский). Документации вполне достаточно для быстрого старта, особенно если есть опыт работы с ORM или Sprig.

Модели

С чего обычно начинается описание ORM-подобных библиотек? Правильно, с моделей! Вот пример из документации:

class Model_Post extends Jelly_Model
{
    public static function initialize(Jelly_Meta $meta)
    {
        $meta->table('posts')
             ->fields(array(
                 'id' => new Field_Primary,
                 'name' => new Field_String,
                 'body' => new Field_Text,
                 'status' => new Field_Enum(array(
                     'choices' => array('draft', 'review', 'published'))),
                 'author' => new Field_BelongsTo,
                 'tags' => new Field_ManyToMany,
             ));
    }
}

Очень похоже на Sprig – все необходимые поля объявляются при инициализации (напомню, что ORM по умолчанию запрашивает описания полей у базы данных), для каждого вида поля создается свой класс (потомок Jelly_Field). У полей есть свойства $in_db (существует ли данное поле в таблице БД), $primary (булевый флаг, является ли поле первичным ключом), $default (значение по умолчанию) и т.д. – большинство свойств знакомы нам по Sprig. Методом table() устанавливается имя таблицы БД (на самом деле это необязательно, т.к. имя для таблицы соответствует рекомендациям ORM и было бы вычислено автоматически).

Параметры модели

Все, что описывает модель в части связи с БД (поля, имя таблицы, имя первичного ключа и т.д.), хранится в объекте класса Jelly_Meta. В вышеприведенном примере метод initialize() модели как раз заполнял переменную $meta, которая будет прикреплена к модели Model_Post. Эти данные выделены в отдельный объект не просто так – класс Jelly хранит (регистрирует) метаданные всех созданных ранее моделей в свойстве $_models, и в дальнейшем ознакомиться с ними можно будет без необходимости инициализировать саму модель. Достаточно вызвать Jelly::meta('post'), и на выходе получим Meta-объект для модели Model_Post.

CRUD

Для загрузки, создания, изменения и удаления объектов в Jelly используются различные методы (как и в Sprig).

Доступ к записям в БД

// загрузка записи с идентификатором = 1
$post = Jelly::select('post', 1);
// то же самое
$post = Jelly::select('post')->load(1);
// загрузка всех записей
$posts = Jelly::select('post')->execute();
// загрузка с условием
$approved_posts = Jelly::select('post')->where('is_approved', '=', 1)->execute();

В первом случае будет извлечена только одна запись, поэтому $post содержит объект Model_Post. В случае же вызова execute() на выходе будет объект класса Jelly_Collection, это что-то вроде ORM_Iterator из ORM второй ветки Kohana.

На самом деле, если вызвать метод limit() с параметром 1, то результат будет содержать одну модель, как и в случае с load(). По сути вызов load($id) просто краткая запись от where('id', '=', $id)->limit(1)->execute().

С объектом Jelly_Collection можно работать также, как и с ORM_Iterator или Database_Result: перебирать элементы в цикле, подсчитать общее число записей в нем, преобразовать в массив с помощью метода as_array($key, $value).

Новая запись

// создание нового объекта
$post = Jelly::factory('post');
// заполняем поля по одиночке
$post->title = 'new post';
// или разом
$post->set(array('text' => 'new post text', 'created' => time()));
// сохраняем
$post->save();

Можно использовать и Jelly::insert('post')->set(...)->execute(), но это не так удобно, по сравнению с созданием модели и ее заполнением. Зато быстрее!

Редактирование записи

$post = Jelly::factory('post');
// устанавливаем нужные значения
$post->title = 'edited post';
// сохраняем. Не забудьте передать идентификатор записи!
$post->save(1);

Похоже на создание новой записи, но тут мы заранее знаем идентификатор записи и меняем значения отдельных ее полей (в данном случае поле `title`) без загрузки самой записи. На самом деле можно было сделать и “по старинке”:

$post = Jelly::select('post', 1);
$post->title = 'edited post';
// модель загружена из БД, передавать идентификатор в метод save() не надо
$post->save();

Усложнение запросов

Как и в случае с ORM, в Jelly для непосредственной работы с базой данных используется Query_Builder, точнее его потомок, Jelly_Builder. Поэтому синтаксис запросов выглядит знакомым, доступны методы where(), join() и т.д.

А теперь представьте себе, что вы часто выбираете записи по определенному условию, например утвержденные администратором/модератором статьи:

$posts = Jelly::select('post')->where('is_approved', '=', 1)->execute();

В ORM такие вещи можно было спрятать в методе модели, примерно так:

public function approved($value = 1)
{
    $this->where('is_approved', '=', $value);
    return $this;
}
$posts = ORM::factory('post')->approved()->find_all();

Однако в Jelly методы select(), insert(), update() и delete() возвращают Jelly_Builder, а не текущую модель, поэтому в модели подобные методы логики приложения создавать бессмысленно. Зато можно создавать свои классы Jelly_Builder, например для модели Model_Post создаем Model_Builder_Post и в нем прописываем нужные методы:

class Model_Builder_Post extends Jelly_Builder {
  public function approved($value = 1)
  {
      return $this->where('is_approved', '=', $value);
  }
}

Jelly очень гибка и имеет множество настроек. В том числе есть и возможность поменять префикс для моделей и билдеров. Берем заглушку classes/jelly.php (Jelly использует ту же тактику избыточного именования моделей, что и Ko3) и меняем свойство $_model_prefix под свои нужды, например ‘myjelly_‘. В результате все модели и билдеры должны будут храниться в директории classes/myjelly, а имена этих классов начинаться не с ‘Model_‘, а с ‘Myjelly_‘. Но, конечно, мало кто будет с этим заморачиваться.

Псевдонимы

Случается, что первичные ключи называются не по “фэн-шую”, например post_id или IdPost, а хотелось бы обращаться по привычному имени id. Выход есть – используйте псевдонимы. Существует два варианта, привычный и инновационный

1. В методе fields() модели объявляете имя поля как Вам удобно, и указываете в свойстве ‘column‘ реальное имя поля. Например, так:
   

   'id'        => new Field_Primary(array('column' => 'post_id')),

   
   В данном способе нет ничего нового, такие псевдонимы доступны как в ORM, так и в Sprig.

2. Сперва по всем правилам объявляете поле, а ниже создаете новые поля, “переадресовывая” их на ранее созданное. Поясню на примере:
   

   'post_id'        => new Field_Primary,
   'id' => 'post_id',

   Теперь можно использовать $post->id, в результате будет отрабатывать поле ‘post_id‘. Можно создать и второй псевдоним, тоже будет работать. А вот по цепочке (id1 -> id -> post_id) не работает, ну и ладно.

Конечно, рекомендуется использовать метод id() для получения значения первичного ключа модели (в ORM его аналогом был метод pk()). Обращаться к именам полей напрямую лучше пореже, дабы не привязываться к потенциально изменчивой структуре БД.

Мета-псевдонимы

Очень интересное и вкусное нововведение. Обычно при объявлении тех же связей мы пишем реальные имена полей (первичных ключей, внешних ключей и т.д.), аналогичные неудобства при заполнении условий Query_Builder‘а (что-то типа where('id', 'IN', $values)). А вот в Jelly есть специальные слова, позволяющие указать на нужные поля без их конкретного имени! Вот их перечень:

• :primary_key – тут все понятно, будет заменено на имя первичного ключа.
• :foreign_key – имя внешнего ключа для других моделей (обычно явно не указывается, поэтому формируется как имя_модели + '_id').
• :name_key – имя “титульного” поля, например ‘username‘ для модели User или ‘title‘ для Post (если конечно Вы соответствующее свойство $name_key указывали в модели). Полезно для получения списка id=>value из набора записей, например $posts->as_array(':primary_key', ':name_key').
• :unique_key. Данный мета-алиас предназначен для работы с уникальными ключами, в основном через Jelly_Builder (аналог стандартного Query_Builder‘а). По умолчанию в моделях Jelly есть только один уникальный ключ – это конечно первичный ключ. Даже если Вы добавите в свойствах какого-либо поля параметр $unique = TRUE, автоматически оно определяться не будет. Надо создавать свой билдер для модели и в нем прописывать метод unique_key($value). Вот как он изначально написан в Jelly_Builder:
  

  	public function unique_key($value)
  	{
  		return $this->_meta->primary_key();
  	}

  Если мы для модели Model_User захотим сделать уникальными поля email и username, то в класса Model_Builder_User создадим свой метод:

  	public function unique_key($id)
  	{
  		if ( ! empty($id) AND is_string($id) AND ! ctype_digit($id))
  		{
  			return validate::email($id) ? 'email' : 'username';
  		}
  		return parent::unique_key($id);
  	}

  В общем, все как и в старом-добром Auth. А дальше уже можно использовать:
  

  $user = Jelly::select('user')->where(':unique_key', '=', $_POST['login'])->load();
  // или более короткая запись
  $user = Jelly::select('user')->load($_POST['login']);
  // еще более короткая запись!
  $user = Jelly::select('user', $_POST['login']);

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

Связи

Естественно, есть поддержка привычных нам типов связей (используем классы Field_HasOne, Field_HasMany, Field_BelongsTo и Field_ManyToMany). Для настройки связи используются три параметра, которые передаются в конструктор:

• ‘column‘ – имя поля в таблице модели, которое является внешним ключом. Естественно, это доступно только для связей BelongsTo, т.к. в остальных случаях внешний ключ выносится в другую модель (и свойство $in_db, упомянутое выше, для этих видов связей равно FALSE).
• ‘foreign‘ – строка с описанием внешнего ключа. Обычно указывается в виде ‘model.field‘, например ‘article.id‘. Если данный параметр не указан, то будет автоматически сгенерировано значение исходя из имени связи, с использованием первичного ключа связанной модели. Также можно указать только имя модели, в этом случае к нему будет добавлен первичный ключ.
• ‘through‘ – этот параметр нужен для связей ManyToMany, чтобы указать промежуточную таблицу. Его можно указать как строку (тогда это должно быть имя промежуточной модели), как массив (поле ‘model‘ определяет имя промежуточной модели, а ‘columns‘ – массив полей с первичными ключами связанных моделей). Если не указывать вообще, сработает автозаполнение, принцип именования промежуточной модели аналогичен ORM‘у (Role_User для моделей User и Role).

Много текста, мало смысла, поэтому вот несколько примеров описания связей для модели Model_User:

// все по умолчанию, связь с моделью Model_Post по ключу user_id
'posts'  => new Jelly_Field_HasMany;
// добавляем отсебятины, пусть внешний ключ называется author_id
'posts'  => new Jelly_Field_HasMany(array('foreign' => 'post.author_id'));
// + меняем имя связи
'articles' => new Jelly_Field_HasMany(array('foreign' => 'post.author_id'));
// добавляем связь для получения отмодерированных статей
'moderated' => new Jelly_Field_HasMany(array('foreign' => 'post.moderator_id'));
 
// по умолчанию промежуточная модель Role_User должна содержить ключи role_id и user_id
'roles' => new Jelly_Field_ManyToMany;
// указываем явно, что в модели Role внешним ключом будет первичный ключ
'roles' => new Jelly_Field_ManyToMany(array('foreign' => 'role.role:primary_key'));
// используем нестандартное имя промежуточной модели
'roles' => new Jelly_Field_ManyToMany(array('through' => 'user_role'));
// в данном примере имя промежуточной модели и содержащиеся в ней ключи нестандартные
'roles' => new Jelly_Field_ManyToMany(array('through' => array('model' => 'user_role', 'columns' => array('userId', 'roleId'))));

Обратите внимание, что при объявлении имен полей в промежуточной модели (параметр ['through']['columns']) важен порядок их следования. Сперва указывается внешний ключ от текущей модели (в данном случае это userId), а потом – от связанной.

Валидация

При объявлении полей модели есть возможность указать и условия валидации (rules/filters/callbacks, а также label). Тут все в принципе аналогично Sprig. Для уникальных полей (свойство $unique == TRUE) автоматически добавляется callback-метод _is_unique() для проверки на наличие проверяемого значения в БД. В случае ошибок при проверке выбрасывается Validate_Exception, поэтому не забывайте оборачивать вызовы validate() и save() в конструкции try ... catch(). Метод validate() возвращает массив проверенных данных в случае успеха.

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

Каждое поле модели реализует метод input($prefix, $data), который должен выводить поле ввода/выбора значения (через представление View). Первый аргумент ($prefix) позволяет указать свой путь для представления, по умолчанию он ‘jelly/field‘ (да, в views/jelly/field/ можно подсмотреть уже имеющиеся заготовки для стандартных типов данных Jelly). Параметр $data позволяет передать в шаблон дополнительные переменные, которые будут добавлены к публичным свойствам поля. Еще в шаблоне будет доступна переменная $field, которая содержит собственно сам выводимый объект Jelly_Field.

Заключение

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

+ неплохая документация, причем сразу в комплекте с модулем.
+ высокая гибкость и настраиваемость, даже выше, чем у Sprig.
+ введение объекта Meta позволяет уменьшить количество запросов к БД, когда нужны только метаданные о моделях.
- относительная сложность по сравнению со Sprig и тем более ORM.

Модуль очень интересный, и в целом сообществу очень понравился (достаточно посмотреть на количество топиков о нем). Разработкой заняты солидные люди, добавляются вспомогательные модули (типа Jelly-Auth), в общем обратите на него внимание

Как мы знаем, основная “фишка” 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. Это будет темой следующего поста.

Для тех, кому лень читать указанное обсуждение, опишу вкратце проблему. Есть запись, которую может оставить как зарегистрированный пользователь, так и гость. Вследствие этого в таблице есть как поле `author_id` (только для зарегистрированных пользователей), так и `author` (там хранится имя, как гостя, так и пользователя). Проблема в том, что гость может использовать только незанятые пользователями имена, т.е. появляется дополнительное правило для некоторых записей в таблице. Правило должно применяться как при валидации новой записи, так и при редактировании существующей.

Освежим в памяти теорию

Один из главных девизов нового модуля ORM – “ленивая загрузка”, так что инициализация свойства $_validate начинается только после первого обращения к нему (а это может быть реализовано двумя методами – check() и validate()). За подготовку объекта Validate отвечает метод _validate(), который создает его, добавляет правила (rules), вызовы (callbacks), фильтры (filters) и метки (labels). Данный метод выполняется, когда методы check() и validate() проверяют свойство $_validate, и оно оказывается не заполнено.

Собственно сама проверка начинается после вызова check(). В объект Validate автоматически подставляются значения полей модели ORM (свойство $_object), включая несуществующие поля (указанные в свойстве $_ignored_columns). Далее выполняется сама проверка ($this->_validate->check()), как результат возвращается TRUE.

Ну уж теперь все ясно!

Конечно, дополнительные правила надо вставлять где-то в промежутке между проверкой и добавлением основных (общих для всех). Для этого подходит метод _validate(). В своей модели мы можем расширить его, добавив в конце свои условия. Для описанной на форуме проблемы получится что-то вроде такого кода:

// classes/model/post.php
protected function _validate()
{
    // не забываем сперва добавить "родные" правила
    parent::_validate();
    // добавляем проверку на доступность имени, если запись оставлена гостем
    if ( is_null($this->author_id) )
    {
        $this->_validate->callback('author', array($this, 'author_available'));
    }
}

Чем отличается запись гостя от записи зарегистрированного пользователя? Поле `author` заполнено и там, и там, а вот `author_id` (идентификатор пользователя) у гостя должен быть NULL. На основании этого рассуждения мы добавляем дополнительную проверку.

Попутно…

В ходе тестов выяснилось, что “ленивая загрузка” не отрабатывает, если создавать объект с передачей идентификатора (типа ORM::factory('article', 1)) и сразу вызывать метод check(). Объект не будет загружен из БД, и в результате получим кучу ошибок валидации. Это в принципе логично, т.к. уже сохраненные объекты обычно не проверяют. Если все же надо сделать проверку, используйте явный вызов метода find() (ORM::factory('article')->find(1)), либо проверку методом loaded().

• “Ленивая загрузка” в ORM позволяет делать дополнительную фильтрацию после обращения к “множественным” свойствам модели. Например, так мы отфильтруем неподтвержденные комментарии к записи в блоге, а также отберем только второй десяток из них:

  $comments = ORM::factory('blog', 1)->comments
            ->where('is_confirmed', '=', 1)
            ->limit(10)
            ->offset(10)
            ->find_all();

  На все это уйдет только один запрос, т.к. он теперь формируется только после явного вызова find_all().

• Так как библиотеки Input теперь нет, очищать данные от XSS придется самостоятельно (Security::xss_clean() вам в руки, можно добавить как фильтр в Validate). Автоматически Ko3 лишь убирает лишние слэши (т.е. можем не думать о magic_quote_qpc) и все переводы строк приводит к единому виду (“\n“). Если надо обратиться к глобальной переменной, но есть сомнения в ее существовании, можно использовать метод arr::get(), он поддерживает установку значения по умолчанию. Например, так: arr::get($_POST, 'text', '');
• Список подключенных модулей может быть откорректирован в любой точке приложения. Метод Kohana::modules($modules) заново подключит все модули, указанные в массиве $modules. При этом ранее подключенные модули будут отброшены. Если вызвать метод без параметров, он вернет текущий список активных модулей. Таким образом, можно на лету подключить модуль X:
  Kohana::modules(arr::merge(Kohana::modules(), array('x' => MODPATH.'x'))). Пути для автозагрузки классов будут заново просчитаны, так что можно добиться изменения порядка активации модулей в списке (это играет роль при работе каскадной файловой системы Kohana).

  Насчет возможной двойной отработки файлов init.php не волнуйтесь – они подгружаются через require_once(). Тем не менее, сама по себе функция довольно затратная, не стоит ее вызывать бездумно.

• Можно кэшировать отдельные участки страницы с помощью класса Fragment:
  

  if ( ! Fragment::load('some_page', 100))
  {
      echo View::factory('some_page_view');
      Fragment::save();
  }

  В данном случае мы проверяем наличие кэшированной версии по ключу ‘some_page‘, устанавливая срок актуальности (lifetime) в 100 секунд. Если фрагмент не найден, надо его отобразить и сразу добавить в кэш (метод Fragment::save()). Если же в кэше есть нужный нам кусок страницы, он отобразится автоматически. По умолчанию lifetime ставится на 30 секунд. Ах да, кэш – файловый, пока что нет библиотеки Cache а-ля Kohana v2.3.4.

• Запросы на добавление записей (INSERT) возвращают массив (последний_сгенерированный_id, количество_вставленных_записей), а для редактирования (UPDATE) и удаления (DELETE) – только количество измененных/удаленных записей.