В прошлой статье я рассматривал один из способов быстрого доступа к переводимым атрибутам. Для того что бы понять о чем вообще идет речь, настоятельно рекомендуется прочитать укзаную статью перед этой ) Для тех, кто уже читал, напомню, что основной цимес состоял в искусственных гетерах и сетерах через hasAccessorMutator(), которые в свою очередь оверрайдились через __call()-функцию шаблона. Очевидный минус этого подхода это невозможность использовать __call() в других шаблонах, что не есть хорошо. Есть более красивый и эффективный способ реализовать такой доступ, причем он изначально был предусмотрен в Doctrine чуть ли не с самых первых версий — это фильтры атрибутов. И снова под катом много кода и текста.
Как же все-таки фильтры используются в Doctrine_Record? Не вдаваясь в продробности, примерная схема выглядит таким образом:
как видно, для любого аттрибута (в том числе и не существующего) делается вызов filterGet() для каждого экземпляра фильтра, назначеного для записи!
Что это может значить для нас? А то, что мы можем использовать родной метод доступа к атрибутам через внешний класс фильтра. По умолчанию в Doctrine_Record установлен только 1 фильтр — Doctrine_Record_Filter_Compound, который отслеживает наличие заданого атрибута, и если его не существует — кидает исключение. Это исключение ловится в Doctrine_Record и либо переходит к следующему фильтру, либо повторно его вызывает, если фильтры закончились. Все достаточно просто и наша задача сводится к тому что бы реализовать свой фильтр, который будет перехватывать вызов атрибутов, которые мы укажем в инициализации и возвращать значения соответствующих полей ассоциации Translation для нашей записи, а для других кидать исключение. Как видно из вставки кода (см. выше), запись вызывает фильтры по порядку и ловит их исключеня либо результат для того, что бы перейти к следующему фильру. Попробуем реализовать такой фильтр.
Для начала, что бы создать какой-либо фильтр, нужно создать класс пронаследованый из Doctrine_Record_Filter и реализовать 2 абстрактных метода Doctrine_Record_Filter::filterGet() и Doctrine_Record_Filter::filterSet(). Как видно из примерной схемы работы геттеров и сеттеров (см. выше) запись вызывает фильтры по порядку, а а случае каких-то ошибок мы должны кидать исключение.
Я не буду на этот раз вдаваться в цепочки рассуждений как надо писать классы, а приведу сразу готовый код фильтра, а потом займемся анализом что и зачем нужно.
Здесь мы проводим инициализацию нашего фильтра, и передаем ему список опций, в которых содержится информация о полях, языке, и загадочном владельце фильтра. Рассмотрим опции поближе (интерфейс аналогичный приведенному в предыдущей статье):
Это набор методов (get/set)Fields(), (get/set)Language(), (get/set)Owner(). В принцие здесь ничего нетревиального, потом подробно рассматривать все не буду. Остановлюсь только getLanguage(), т.к. в нем опять появляется загадочный владелец:
Как видно, owner нам нужен исключительно для того, что бы запросить язык, если его собственное значение не указано. Это сделано для того что бы позволить этому фильтру интегрироваться в другую структуру. В моем случае это модифицированый шаблон Of_ExtDoctrine_I18n_EasyAccess_Helper, аналог которого я рассматривал в предыдущей статье. Owner должен следовать интерфейсу Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface, в котором содержится только один публичный метод getLanguage()
Вот в конце концов и подобрались к самим методам, которые реализуют необходимый функционал фильтра.
Видно, что они практически не отличаются от accessor'ов и mutator'ов из прошлой части и состоят из 2х методов фильтрации и 2х искусственных геттеров и сеттеров. Я их сделал потому что хотелось бы оставить возможность получить значение перевода для произвольного языка при случае.
Также в геттере появилась возможность отключать или включать возможность поиска первого переведенного значения в случае, когда перевод для текущего языка пуст. По умолчанию он включен, но надо будет как-нибудь вынести его в дополнительную опцию.
Создадим запись аналогичную той, что в первой части и подключим фильтр.
При доступе к аттрибуту «description» сработает фильтр и вернется значение для английского языка, а вот если обратится к неуказаному атрибуту фильтр кинет исключение, а следующий за ним фильтр Doctrine_Record_Filter_Compound скажет нам о том, что такого атрибута не существует
Аналогично будет и для записи в атрибут, я ее рассматривать не буду.
Раньше я рассматривал доступ к аттрибутам через шаблон Of_ExtDoctrine_I18n_Template. Попробуем изменить его таким образом что бы вместо hasAccessorMutator использовался наш фильтр. Попутно изменю и название, что бы оформить нашу систему в один пакет Of_ExtDoctrine_I18n_EasyAccess. Сразу привожу исходный код класса.
В шаблоне практически ничего не изменлось, мы просто избавились от методов чтения/записи в Translation, т.к. они перенесены в фильтр, а также метода __call() потому что он уже не нужен по тем же причинам.
Установка фильтра в таблицу происходит в методе setUp() как и раньше, добавлена опция disableFilter если по каким-то причинам нам нужно отлючить фильтр. В качестве владельца фильтра мы устанавливаем наш шаблон и передаем пустое заначение языка, что позволяет шаблону контролировать текущее значение языка фильтра, метод Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface::getLanguage() у нас уже реализован. Все, остается подключить шаблон в нашей демо-записи и провести тесты
Такая реализация доступа гораздо удобнее, и, как оказалось, гораздо быстрее способа описаного ранее. Следующим шагом будет возможность доступа к атрибутам при различных методах гидрации, например в Doctrine::HYDRATE_ARRAY, т.к. там не создается объектов и мы все равно будем вынуждены пользоваться Translation-ассоциацией (в данном случае вложеным массивом).
Все классы одним архивом можно найти здесь
PS. Внимательный читатель наверняка мог заметить, что в фильтре повторяется обвяз для полей и языка, описаный в шаблоне. Это было использовано для того, что бы можно было использовать фильтр как stand-alone компонент не прибегая к шаблону, что я считаю хорошим тоном для подобного рода систем.
В этой статье код был подсвечен при помощи Source Code Highlighter.
Быстрый доступ к переводимым атрибутам через фильры
Как же все-таки фильтры используются в Doctrine_Record? Не вдаваясь в продробности, примерная схема выглядит таким образом:
- $record->attribute — скрипт запрашивает некий атрибут
- вызывается метод Doctrine::__get('attribute'), который вызывает Doctrine_Record::get('attribute'), а он в свою очередь метод Doctrine::_get('attribute').
- в процессе этой очереди происходят проверки на наличие accessor'ов и mutator'ов (та же очередь соответстует и сеттерам), наличия ассоциаций и др. и в самом конце вызывается прелюбопытнейшая конструкция...
// код из Doctrine_Record::_get() в самом конце метода
foreach ($this->_table->getFilters() as $filter) {
try {
$value = $filter->filterGet($this, $fieldName);
$success = true;
} catch (Doctrine_Exception $e) {}
}
if ($success) {
return $value;
} else {
throw $e;
}
как видно, для любого аттрибута (в том числе и не существующего) делается вызов filterGet() для каждого экземпляра фильтра, назначеного для записи!
Что это может значить для нас? А то, что мы можем использовать родной метод доступа к атрибутам через внешний класс фильтра. По умолчанию в Doctrine_Record установлен только 1 фильтр — Doctrine_Record_Filter_Compound, который отслеживает наличие заданого атрибута, и если его не существует — кидает исключение. Это исключение ловится в Doctrine_Record и либо переходит к следующему фильтру, либо повторно его вызывает, если фильтры закончились. Все достаточно просто и наша задача сводится к тому что бы реализовать свой фильтр, который будет перехватывать вызов атрибутов, которые мы укажем в инициализации и возвращать значения соответствующих полей ассоциации Translation для нашей записи, а для других кидать исключение. Как видно из вставки кода (см. выше), запись вызывает фильтры по порядку и ловит их исключеня либо результат для того, что бы перейти к следующему фильру. Попробуем реализовать такой фильтр.
Фильтр
Для начала, что бы создать какой-либо фильтр, нужно создать класс пронаследованый из Doctrine_Record_Filter и реализовать 2 абстрактных метода Doctrine_Record_Filter::filterGet() и Doctrine_Record_Filter::filterSet(). Как видно из примерной схемы работы геттеров и сеттеров (см. выше) запись вызывает фильтры по порядку, а а случае каких-то ошибок мы должны кидать исключение.
Я не буду на этот раз вдаваться в цепочки рассуждений как надо писать классы, а приведу сразу готовый код фильтра, а потом займемся анализом что и зачем нужно.
/**
* EasyAccess package filter. Implements access to record's properties as for translated in I18n.
*
* Can be used as a part of Of_ExtDoctrine_I18n_Helper system, or as stand-alone filter both.
*
* @author OmeZ
* @version 1.0
* @license www.opensource.org/licenses/lgpl-license.php LGPL
* @package Of_ExtDoctrine_I18n_EasyAccess
*/
class Of_ExtDoctrine_I18n_EasyAccess_Filter extends Doctrine_Record_Filter {
/**
* Fields
*
* @var array
*/
protected $_fields = array();
/**
* Language
*
* @var string
*/
protected $_language;
/**
* @var Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface
*/
protected $_owner;
/**
* Constructs new filter with options
*
* @param array $options
* @return void
*/
public function __construct(array $options) {
if (isset($options['fields'])) $this->setFields($options['fields']);
if (isset($options['language'])) $this->setLanguage($options['language']);
if (isset($options['owner'])) $this->setOwner($options['owner']);
}
/**
* Returns owner of filter
*
* @return Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface
*/
public function getOwner() {
return $this->_owner;
}
/**
* Sets owner for filter
*
* @param Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface $owner
* @return Of_ExtDoctrine_I18n_EasyAccess_Filter
*/
public function setOwner(Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface $owner) {
$this->_owner = $owner;
return $this;
}
/**
* Returns fields aliases for filter
*
* @return array
*/
public function getFields() {
return $this->_fields;
}
/**
* Sets fields aliases for filter
*
* @param $fields
* @return Of_ExtDoctrine_I18n_EasyAccess_Filter
*/
public function setFields($fields) {
$this->_fields = (array)$fields;
return $this;
}
/**
* Returns default language for filter
*
* @return string
*/
public function getLanguage() {
if ($this->_language !== null) {
return $this->_language;
} elseif ($this->_owner) {
return $this->_owner->getLanguage();
} else {
require_once 'Of/ExtDoctrine/I18n/EasyAccess/Exception.php';
throw new Of_ExtDoctrine_I18n_EasyAccess_Exception('Impossible to detect language');
}
}
/**
* Sets language to filter
*
* @return Of_ExtDoctrine_I18n_EasyAccess_Filter
*/
public function setLanguage($language) {
$this->_language = $language;
return $this;
}
/**
* Returns value of translatable attribute
*
* @param Doctrine_Record $record
* @param string $name
* @return mixed
*/
public function filterGet(Doctrine_Record $record, $name) {
return $this->getTranslation($record, $name, $this->getLanguage());
}
/**
* Sets value to translatable attribute
*
* @param Doctrine_Record $record
* @param string $name
* @param mixed $value
* @return void
*/
public function filterSet(Doctrine_Record $record, $name, $value) {
return $this->setTranslation($record, $name, $value, $this->getLanguage());
}
/**
* Language dependent getter to translatable attribute
*
* @param Doctrine_Record $record
* @param string $name
* @param string $language
* @param boolean $return_first_found
* @return mixed
*/
public function getTranslation(Doctrine_Record $record, $name, $language = null, $return_first_found = true) {
if (in_array($name, $this->_fields)) {
$language = empty($language)?(string)$this->getLanguage():(string)$language;
if ($record->hasRelation('Translation')) {
if ($record->Translation->contains($language)) {
return $record->Translation[$language][$name];
} elseif ($return_first_found && $record->Translation->count()) {
foreach ($record->Translation as $translation)
if (!empty($translation[$name]))
return $translation[$name];
return null;
} else return null;
} else return null;
} else {
require_once 'Of/ExtDoctrine/I18n/EasyAccess/NotTranslatableException.php';
throw new Of_ExtDoctrine_I18n_EasyAccess_NotTranslatableException("Field {$name} is not marked as easy getter to tranlsatable attribute in ".get_class($record));
}
}
/**
* Language dependent setter to translatable attribute
*
* @param Doctrine_Record $record
* @param string $name
* @param mixed $value
* @param string $language
* @return void
*/
public function setTranslation(Doctrine_Record $record, $name, $value, $language = null) {
if (in_array($name, $this->_fields)) {
$language = empty($language)?(string)$this->getLanguage():(string)$language;
if ($record->hasRelation('Translation')) {
$record->Translation[$language][$name] = $value;
}
} else {
require_once 'Of/ExtDoctrine/I18n/EasyAccess/NotTranslatableException.php';
throw new Of_ExtDoctrine_I18n_EasyAccess_NotTranslatableException("Field {$name} is not marked as easy setter to tranlsatable attribute in ".get_class($record));
}
}
}
Analysis time!
Конструктор
/**
* Constructs new filter with options
*
* @param array $options
* @return void
*/
public function __construct(array $options) {
if (isset($options['fields'])) $this->setFields($options['fields']);
if (isset($options['language'])) $this->setLanguage($options['language']);
if (isset($options['owner'])) $this->setOwner($options['owner']);
}
Здесь мы проводим инициализацию нашего фильтра, и передаем ему список опций, в которых содержится информация о полях, языке, и загадочном владельце фильтра. Рассмотрим опции поближе (интерфейс аналогичный приведенному в предыдущей статье):
- 'fields' — список атрибутов которые мы будем отслеживать. Забегая вперед скажу что если мы укажем несуществующий атрибут и обратимся к нему — фильтр кинет исключение
- 'language' — язык по умолчанию, который мы будем использовать для доступа к аттрибутам
- 'owner' — загадочный владелец фильтра. Эта опция используется для того что бы указать какой-нибудь объект (интерфейса Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface), к которому будет обращаться фильтр что бы получить язык, если он не был до этого задан. Но об этом потом
Методы установки и получения опций
Это набор методов (get/set)Fields(), (get/set)Language(), (get/set)Owner(). В принцие здесь ничего нетревиального, потом подробно рассматривать все не буду. Остановлюсь только getLanguage(), т.к. в нем опять появляется загадочный владелец:
/**
* Returns default language for filter
*
* @return string
*/
public function getLanguage() {
if ($this->_language !== null) {
return $this->_language;
} elseif ($this->_owner) {
return $this->_owner->getLanguage();
} else {
require_once 'Of/ExtDoctrine/I18n/EasyAccess/Exception.php';
throw new Of_ExtDoctrine_I18n_EasyAccess_Exception('Impossible to detect language');
}
}
Как видно, owner нам нужен исключительно для того, что бы запросить язык, если его собственное значение не указано. Это сделано для того что бы позволить этому фильтру интегрироваться в другую структуру. В моем случае это модифицированый шаблон Of_ExtDoctrine_I18n_EasyAccess_Helper, аналог которого я рассматривал в предыдущей статье. Owner должен следовать интерфейсу Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface, в котором содержится только один публичный метод getLanguage()
interface Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface {
/**
* Returns language for inherited components
*
* @return string
*/
public function getLanguage();
}
Методы фильтра
Вот в конце концов и подобрались к самим методам, которые реализуют необходимый функционал фильтра.
/**
* Returns value of translatable attribute
*
* @param Doctrine_Record $record
* @param string $name
* @return mixed
*/
public function filterGet(Doctrine_Record $record, $name) {
return $this->getTranslation($record, $name, $this->getLanguage());
}
/**
* Sets value to translatable attribute
*
* @param Doctrine_Record $record
* @param string $name
* @param mixed $value
* @return void
*/
public function filterSet(Doctrine_Record $record, $name, $value) {
return $this->setTranslation($record, $name, $value, $this->getLanguage());
}
/**
* Language dependent getter to translatable attribute
*
* @param Doctrine_Record $record
* @param string $name
* @param string $language
* @param boolean $return_first_found
* @return mixed
*/
public function getTranslation(Doctrine_Record $record, $name, $language = null, $return_first_found = true) {
if (in_array($name, $this->_fields)) {
$language = empty($language)?(string)$this->getLanguage():(string)$language;
if ($record->hasRelation('Translation')) {
if ($record->Translation->contains($language)) {
return $record->Translation[$language][$name];
} elseif ($return_first_found && $record->Translation->count()) {
foreach ($record->Translation as $translation)
if (!empty($translation[$name]))
return $translation[$name];
return null;
} else return null;
} else return null;
} else {
require_once 'Of/ExtDoctrine/I18n/EasyAccess/NotTranslatableException.php';
throw new Of_ExtDoctrine_I18n_EasyAccess_NotTranslatableException("Field {$name} is not marked as easy getter to tranlsatable attribute in ".get_class($record));
}
}
/**
* Language dependent setter to translatable attribute
*
* @param Doctrine_Record $record
* @param string $name
* @param mixed $value
* @param string $language
* @return void
*/
public function setTranslation(Doctrine_Record $record, $name, $value, $language = null) {
if (in_array($name, $this->_fields)) {
$language = empty($language)?(string)$this->getLanguage():(string)$language;
if ($record->hasRelation('Translation')) {
$record->Translation[$language][$name] = $value;
}
} else {
require_once 'Of/ExtDoctrine/I18n/EasyAccess/NotTranslatableException.php';
throw new Of_ExtDoctrine_I18n_EasyAccess_NotTranslatableException("Field {$name} is not marked as easy setter to tranlsatable attribute in ".get_class($record));
}
}
Видно, что они практически не отличаются от accessor'ов и mutator'ов из прошлой части и состоят из 2х методов фильтрации и 2х искусственных геттеров и сеттеров. Я их сделал потому что хотелось бы оставить возможность получить значение перевода для произвольного языка при случае.
Также в геттере появилась возможность отключать или включать возможность поиска первого переведенного значения в случае, когда перевод для текущего языка пуст. По умолчанию он включен, но надо будет как-нибудь вынести его в дополнительную опцию.
Подключение фильтра
Создадим запись аналогичную той, что в первой части и подключим фильтр.
class Product extends Doctrine_Record {
public function setTableDefinition() {
//....
$this->hasColumn('name', 'string', 255);
$this->hasColumn('description', 'string');
//....
}
public function setUp() {
$this->actAs('I18n', array(
'fields'=>array('name', 'description')
));
$i18nFilter = new Of_ExtDoctrine_I18n_EasyAccess_Filter(array(
'language'=>'en',
'fields'=>array('name', 'description') // используем все доступные для перевода поля
));
$this->getTable()->unshiftFilter($i18nFilter);
}
}
$record = new Product();
$record->description = 'my description'; // аналогично $record->Translation['en']->description
echo $record->description; // вывод аналогичен echo $record->Translation['en']->description
При доступе к аттрибуту «description» сработает фильтр и вернется значение для английского языка, а вот если обратится к неуказаному атрибуту фильтр кинет исключение, а следующий за ним фильтр Doctrine_Record_Filter_Compound скажет нам о том, что такого атрибута не существует
try {
echo $record->lol; // кинет эксепшн
} catch (Of_ExtDoctrine_I18n_EasyAccess_NotTranslatableException $e) {
//...
}
Аналогично будет и для записи в атрибут, я ее рассматривать не буду.
Интеграция с шаблоном
Раньше я рассматривал доступ к аттрибутам через шаблон Of_ExtDoctrine_I18n_Template. Попробуем изменить его таким образом что бы вместо hasAccessorMutator использовался наш фильтр. Попутно изменю и название, что бы оформить нашу систему в один пакет Of_ExtDoctrine_I18n_EasyAccess. Сразу привожу исходный код класса.
/**
* Temlate implements extrabehavior for standard Doctrine I18n template.
*
* @author OmeZ
* @version 1.7
* @license www.opensource.org/licenses/lgpl-license.php LGPL
* @package Of_ExtDoctrine_I18n_EasyAccess
*/
class Of_ExtDoctrine_I18n_EasyAccess_Helper extends Doctrine_Template implements Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface {
protected $_options = array(
'language'=>null,
'fields'=>null,
'disableFilter'=>false,
);
/**
* Holds default language for all behaviors
*
* @var string
*/
static protected $_defaultLanguage;
/**
* Holds language for current model behavior
*
* @var string
*/
protected $_language;
/**
* EasyAccess filter
*
* @var Of_ExtDoctrine_I18n_EasyAccess_Filter
*/
protected $_easyaccess_filter;
public function setUp() {
$language = $this->getOption('language');
if ($language) $this->setLanguage($language);
// Adds filter for access to properties, this can be used as stand-alone plugin
if (!$this->getOption('disableFilter')) {
require_once 'Of/ExtDoctrine/I18n/EasyAccess/Filter.php';
$this->_easyaccess_filter = new Of_ExtDoctrine_I18n_EasyAccess_Filter(array(
'owner'=>$this,
'language'=>null, // this value will make filter access to template getLanguage() method
'fields'=>$this->getOption('fields', array())
));
$this->_table->unshiftFilter($this->_easyaccess_filter);
}
// adds listener to manage Doctrine_Query hydrations. Will add translatable props as keys in
// array when HYDRATE_ARRAY, or mapped values in records. This can be used as stand-alone plugin
}
/**
* Returns default language for all behaviors
*
* @return string
*/
static public function getDefaultLanguage() {
return (string)self::$_defaultLanguage;
}
/**
* Sets default language for all behaviors
*
* @param string $language
* @return void
*/
static public function setDefaultLanguage($language) {
self::$_defaultLanguage = $language;
}
/**
* Returns current language behavior
*
* @return void
*/
public function getLanguage($without_static = false) {
if ($this->_language === null && !$without_static) return self::getDefaultLanguage();
else return (string)$this->_language;
}
/**
* Sets current behavior language
*
* @param $language
* @return string
*/
public function setLanguage($language) {
$this->_language = $language;
}
}
В шаблоне практически ничего не изменлось, мы просто избавились от методов чтения/записи в Translation, т.к. они перенесены в фильтр, а также метода __call() потому что он уже не нужен по тем же причинам.
Установка фильтра в таблицу происходит в методе setUp() как и раньше, добавлена опция disableFilter если по каким-то причинам нам нужно отлючить фильтр. В качестве владельца фильтра мы устанавливаем наш шаблон и передаем пустое заначение языка, что позволяет шаблону контролировать текущее значение языка фильтра, метод Of_ExtDoctrine_I18n_EasyAccess_OwnerInterface::getLanguage() у нас уже реализован. Все, остается подключить шаблон в нашей демо-записи и провести тесты
class Product extends Doctrine_Record {
public function setTableDefinition() {
//....
$this->hasColumn('name', 'string', 255);
$this->hasColumn('description', 'string');
//....
}
public function setUp() {
$this->actAs('I18n', array(
'fields'=>array('name', 'description')
));
$this->actAs(new Of_ExtDoctrine_I18n_EasyAccess_Helper(array(
'fields'=>array('name', 'description') // используем все доступные для перевода поля
)));
}
}
$record = new Product();
$record->description = 'my description'; // аналогично $record->Translation['en']->description
echo $record->description; // вывод аналогичен echo $record->Translation['en']->description
$record->setLanguage('ru'); // установим русский язык по дефолту
echo $record->description; // выведет 'my description', т.к. перевода для русского нет и фильтр ищет первый доступный перевод
Заключение
Такая реализация доступа гораздо удобнее, и, как оказалось, гораздо быстрее способа описаного ранее. Следующим шагом будет возможность доступа к атрибутам при различных методах гидрации, например в Doctrine::HYDRATE_ARRAY, т.к. там не создается объектов и мы все равно будем вынуждены пользоваться Translation-ассоциацией (в данном случае вложеным массивом).
Все классы одним архивом можно найти здесь
PS. Внимательный читатель наверняка мог заметить, что в фильтре повторяется обвяз для полей и языка, описаный в шаблоне. Это было использовано для того, что бы можно было использовать фильтр как stand-alone компонент не прибегая к шаблону, что я считаю хорошим тоном для подобного рода систем.
В этой статье код был подсвечен при помощи Source Code Highlighter.