Skip to content
Permalink
Browse files

Adding doc blocks for TranslateBehavior

  • Loading branch information...
lorenzo committed Jan 26, 2014
1 parent 878b587 commit f2d58a58739664dc241274d07158ea97a63f5f32
Showing with 83 additions and 1 deletion.
  1. +83 −1 src/Model/Behavior/TranslateBehavior.php
@@ -21,6 +21,18 @@
use Cake\ORM\Table;
use Cake\ORM\TableRegistry;
/**
* This behavior provides a way to translate dynamic data by keeping translations
* in a separate table linked to the original record from another one. Translated
* fields can be configured to override those in the main table when fetched or
* put aside into another property for the same entity.
*
* If you wish to override fields, you need to call the `locale` method in this
* behavior for setting the language you want to fetch from the translations table.
*
* If you want to bring all or certain languages for each of the fetched records,
* you can use the custom `translations` finders that is exposed to the table.
*/
class TranslateBehavior extends Behavior {
/**
@@ -30,12 +42,18 @@ class TranslateBehavior extends Behavior {
*/
protected $_table;
/**
* The locale name that will be used to override fields in the bound table
* from the translations table
*
* @var string
*/
protected $_locale;
/**
* Default config
*
* These are merged with user-provided config when the behavior is used.
* These are merged with user-provided configuration when the behavior is used.
*
* @var array
*/
@@ -58,6 +76,16 @@ public function __construct(Table $table, array $config = []) {
$this->setupFieldAssociations($fields);
}
/**
* Creates the associations between the bound table and every field passed to
* this method.
*
* Additionally it creates a `I18n` HasMany association that will be
* used for fetching all translations for each record in the bound table
*
* @param array $fields list of fields to create associations for
* @return void
*/
public function setupFieldAssociations($fields) {
$alias = $this->_table->alias();
foreach ($fields as $field) {
@@ -85,6 +113,15 @@ public function setupFieldAssociations($fields) {
]);
}
/**
* Callback method that listens to the `beforeFind` event in the bound
* table. It modifies the passed query by eager loading the translated fields
* and adding a formatter to copy the values into the main table records.
*
* @param \Cake\Event\Event $event
* @param \Cake\ORM\Query $query
* @return void
*/
public function beforeFind(Event $event, $query) {
$locale = $this->locale();
@@ -110,13 +147,43 @@ public function beforeFind(Event $event, $query) {
}, $query::PREPEND);
}
/**
* Sets all future finds for the bound table to also fetch translated fields for
* the passed locale. If no value is passed, it returns the currently configured
* locale
*
* @param string $locale The locale to use for fetching translated records
* @return string
*/
public function locale($locale = null) {
if ($locale === null) {
return $this->_locale;
}
return $this->_locale = (string)$locale;
}
/**
* Custom finder method used to retrieve all translations for he found records.
* Fetched translations can be filtered by locale by passing the `locales` key
* in the options array.
*
* Translated values will be found for each entity under the property `_translations`,
* containing an array indexed by locale name.
*
* ### Example:
*
* {{{
* $article = $articles->find('translations', ['locales' => ['eng', 'deu'])->first();
* $englishTranslatedFields = $article->get('_translations')['eng'];
* }}}
*
* If the `locales` array is not passed, it will bring all translations found
* for each record.
*
* @param \Cake\ORM\Query $query the original query to modify
* @param array $options
* @return \Cake\ORM\Query
*/
public function findTranslations($query, $options) {
$locales = isset($options['locales']) ? $options['locales'] : [];
return $query
@@ -131,6 +198,14 @@ public function findTranslations($query, $options) {
}, $query::PREPEND);
}
/**
* Modifies the results from a table find in order to merge the translated fields
* into each entity for a given locale.
*
* @param \Cake\ORM\ResultSetDecorator $results
* @param string $locale
* @return \Cake\Collection\Collection
*/
protected function _rowMapper($results, $locale) {
return $results->map(function($row) use ($locale) {
$options = ['setter' => false, 'guard' => false];
@@ -155,6 +230,13 @@ protected function _rowMapper($results, $locale) {
});
}
/**
* Modifies the results from a table find in order to merge full translation records
* into each entity under the `_translations` key
*
* @param \Cake\ORM\ResultSetDecorator $results
* @return \Cake\Collection\Collection
*/
protected function _groupTranslations($results) {
return $results->map(function($row) {
$translations = (array)$row->get('_i18n');

0 comments on commit f2d58a5

Please sign in to comment.
You can’t perform that action at this time.