EavStrategy
in package
implements
TranslateStrategyInterface
uses
InstanceConfigTrait, LocatorAwareTrait, TranslateStrategyTrait
This class 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 finder of TranslateBehavior that is
exposed to the table.
Table of Contents
Interfaces
- TranslateStrategyInterface
- This interface describes the methods for translate behavior strategies.
Properties
- $_config : array<string, mixed>
- Runtime config
- $_configInitialized : bool
- Whether the config property has already been configured with defaults
- $_defaultConfig : array<string, mixed>
- Default config
- $_tableLocator : LocatorInterface|null
- Table locator instance
- $defaultTable : string|null
- This object's default table alias.
- $locale : string|null
- The locale name that will be used to override fields in the bound table from the translations table
- $table : Table
- Table instance
- $translationTable : Table
- Instance of Table responsible for translating
Methods
- __construct() : mixed
- Constructor
- afterSave() : void
- Unsets the temporary `_i18n` property after the entity has been saved
- beforeFind() : void
- 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.
- beforeSave() : void
- Modifies the entity before it is saved so that translated fields are persisted in the database too.
- buildMarshalMap() : array<string|int, mixed>
- Build a set of properties that should be included in the marshalling process.
- configShallow() : $this
- Merge provided config with existing config. Unlike `config()` which does a recursive merge for nested keys, this method does a simple merge.
- fetchTable() : Table
- Convenience method to get a table instance.
- getConfig() : mixed
- Returns the config.
- getConfigOrFail() : mixed
- Returns the config for this specific key.
- getLocale() : string
- Returns the current locale.
- getTableLocator() : LocatorInterface
- Gets the table locator.
- getTranslationTable() : Table
- Return translation table instance.
- groupTranslations() : CollectionInterface
- Modifies the results from a table find in order to merge full translation records into each entity under the `_translations` key.
- setConfig() : $this
- Sets the config.
- setLocale() : $this
- Sets the locale to be used.
- setTableLocator() : $this
- Sets the table locator.
- translationField() : string
- Returns a fully aliased field name for translated fields.
- _configDelete() : void
- Deletes a single config key.
- _configRead() : mixed
- Reads a config key.
- _configWrite() : void
- Writes a config key.
- bundleTranslatedFields() : void
- Helper method used to generated multiple translated field entities out of the data found in the `_translations` property in the passed entity. The result will be put into its `_i18n` property.
- findExistingTranslations() : array<string|int, mixed>
- Returns the ids found for each of the condition arrays passed for the translations table. Each records is indexed by the corresponding position to the conditions array.
- rowMapper() : CollectionInterface
- Modifies the results from a table find in order to merge the translated fields into each entity for a given locale.
- setupAssociations() : void
- Creates the associations between the bound table and every field passed to this method.
- unsetEmptyFields() : void
- Unset empty translations to avoid persistence.
Properties
$_config
Runtime config
protected
array<string, mixed>
$_config
= []
$_configInitialized
Whether the config property has already been configured with defaults
protected
bool
$_configInitialized
= false
$_defaultConfig
Default config
protected
array<string, mixed>
$_defaultConfig
= ['fields' => [], 'translationTable' => 'I18n', 'defaultLocale' => null, 'referenceName' => null, 'allowEmptyTranslations' => true, 'onlyTranslated' => false, 'strategy' => 'subquery', 'tableLocator' => null, 'validator' => false]
These are merged with user-provided configuration.
$_tableLocator
Table locator instance
protected
LocatorInterface|null
$_tableLocator
$defaultTable
This object's default table alias.
protected
string|null
$defaultTable
= null
$locale
The locale name that will be used to override fields in the bound table from the translations table
protected
string|null
$locale
$table
Table instance
protected
Table
$table
$translationTable
Instance of Table responsible for translating
protected
Table
$translationTable
Methods
__construct()
Constructor
public
__construct(Table $table[, array<string, mixed> $config = [] ]) : mixed
Parameters
- $table : Table
-
The table this strategy is attached to.
- $config : array<string, mixed> = []
-
The config for this strategy.
afterSave()
Unsets the temporary `_i18n` property after the entity has been saved
public
afterSave(EventInterface $event, EntityInterface $entity) : void
Parameters
- $event : EventInterface
-
The beforeSave event that was fired
- $entity : EntityInterface
-
The entity that is going to be saved
beforeFind()
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.
public
beforeFind(EventInterface $event, Query $query, ArrayObject $options) : void
Parameters
- $event : EventInterface
-
The beforeFind event that was fired.
- $query : Query
-
Query
- $options : ArrayObject
-
The options for the query
beforeSave()
Modifies the entity before it is saved so that translated fields are persisted in the database too.
public
beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options) : void
Parameters
- $event : EventInterface
-
The beforeSave event that was fired
- $entity : EntityInterface
-
The entity that is going to be saved
- $options : ArrayObject
-
the options passed to the save method
buildMarshalMap()
Build a set of properties that should be included in the marshalling process.
public
buildMarshalMap(Marshaller $marshaller, array<string|int, mixed> $map, array<string, mixed> $options) : array<string|int, mixed>
Add in _translations marshalling handlers. You can disable marshalling
of translations by setting 'translations' => false in the options
provided to Table::newEntity() or Table::patchEntity().
Parameters
- $marshaller : Marshaller
-
The marhshaller of the table the behavior is attached to.
- $map : array<string|int, mixed>
-
The property map being built.
- $options : array<string, mixed>
-
The options array used in the marshalling call.
Return values
array<string|int, mixed> —A map of [property => callable] of additional properties to marshal.
configShallow()
Merge provided config with existing config. Unlike `config()` which does a recursive merge for nested keys, this method does a simple merge.
public
configShallow(array<string, mixed>|string $key[, mixed|null $value = null ]) : $this
Setting a specific value:
$this->configShallow('key', $value);
Setting a nested value:
$this->configShallow('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->configShallow(['one' => 'value', 'another' => 'value']);
Parameters
- $key : array<string, mixed>|string
-
The key to set, or a complete array of configs.
- $value : mixed|null = null
-
The value to set.
Return values
$thisfetchTable()
Convenience method to get a table instance.
public
fetchTable([string|null $alias = null ][, array<string, mixed> $options = [] ]) : Table
Parameters
- $alias : string|null = null
-
The alias name you want to get. Should be in CamelCase format. If
nullthen the value of $defaultTable property is used. - $options : array<string, mixed> = []
-
The options you want to build the table with. If a table has already been loaded the registry options will be ignored.
Tags
Return values
TablegetConfig()
Returns the config.
public
getConfig([string|null $key = null ][, mixed $default = null ]) : mixed
Usage
Reading the whole config:
$this->getConfig();
Reading a specific value:
$this->getConfig('key');
Reading a nested value:
$this->getConfig('some.nested.key');
Reading with default value:
$this->getConfig('some-key', 'default-value');
Parameters
- $key : string|null = null
-
The key to get or null for the whole config.
- $default : mixed = null
-
The return value when the key does not exist.
Return values
mixed —Configuration data at the named key or null if the key does not exist.
getConfigOrFail()
Returns the config for this specific key.
public
getConfigOrFail(string $key) : mixed
The config value for this key must exist, it can never be null.
Parameters
- $key : string
-
The key to get.
Tags
Return values
mixed —Configuration data at the named key
getLocale()
Returns the current locale.
public
getLocale() : string
If no locale has been explicitly set via setLocale(), this method will return
the currently configured global locale.
Tags
Return values
stringgetTableLocator()
Gets the table locator.
public
getTableLocator() : LocatorInterface
Return values
LocatorInterfacegetTranslationTable()
Return translation table instance.
public
getTranslationTable() : Table
Return values
TablegroupTranslations()
Modifies the results from a table find in order to merge full translation records into each entity under the `_translations` key.
public
groupTranslations(ResultSetInterface $results) : CollectionInterface
Parameters
- $results : ResultSetInterface
-
Results to modify.
Return values
CollectionInterfacesetConfig()
Sets the config.
public
setConfig(array<string, mixed>|string $key[, mixed|null $value = null ][, bool $merge = true ]) : $this
Usage
Setting a specific value:
$this->setConfig('key', $value);
Setting a nested value:
$this->setConfig('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->setConfig(['one' => 'value', 'another' => 'value']);
Parameters
- $key : array<string, mixed>|string
-
The key to set, or a complete array of configs.
- $value : mixed|null = null
-
The value to set.
- $merge : bool = true
-
Whether to recursively merge or overwrite existing config, defaults to true.
Tags
Return values
$thissetLocale()
Sets the locale to be used.
public
setLocale(string|null $locale) : $this
When fetching records, the content for the locale set via this method, and likewise when saving data, it will save the data in that locale.
Note that in case an entity has a _locale property set, that locale
will win over the locale set via this method (and over the globally
configured one for that matter)!
Parameters
- $locale : string|null
-
The locale to use for fetching and saving records. Pass
nullin order to unset the current locale, and to make the behavior fall back to using the globally configured locale.
Return values
$thissetTableLocator()
Sets the table locator.
public
setTableLocator(LocatorInterface $tableLocator) : $this
Parameters
- $tableLocator : LocatorInterface
-
LocatorInterface instance.
Return values
$thistranslationField()
Returns a fully aliased field name for translated fields.
public
translationField(string $field) : string
If the requested field is configured as a translation field, the content
field with an alias of a corresponding association is returned. Table-aliased
field name is returned for all other fields.
Parameters
- $field : string
-
Field name to be aliased.
Return values
string_configDelete()
Deletes a single config key.
protected
_configDelete(string $key) : void
Parameters
- $key : string
-
Key to delete.
Tags
_configRead()
Reads a config key.
protected
_configRead(string|null $key) : mixed
Parameters
- $key : string|null
-
Key to read.
_configWrite()
Writes a config key.
protected
_configWrite(array<string, mixed>|string $key, mixed $value[, string|bool $merge = false ]) : void
Parameters
- $key : array<string, mixed>|string
-
Key to write to.
- $value : mixed
-
Value to write.
- $merge : string|bool = false
-
True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Tags
bundleTranslatedFields()
Helper method used to generated multiple translated field entities out of the data found in the `_translations` property in the passed entity. The result will be put into its `_i18n` property.
protected
bundleTranslatedFields(EntityInterface $entity) : void
Parameters
- $entity : EntityInterface
-
Entity
findExistingTranslations()
Returns the ids found for each of the condition arrays passed for the translations table. Each records is indexed by the corresponding position to the conditions array.
protected
findExistingTranslations(array<string|int, mixed> $ruleSet) : array<string|int, mixed>
Parameters
- $ruleSet : array<string|int, mixed>
-
An array of array of conditions to be used for finding each
Return values
array<string|int, mixed>rowMapper()
Modifies the results from a table find in order to merge the translated fields into each entity for a given locale.
protected
rowMapper(ResultSetInterface $results, string $locale) : CollectionInterface
Parameters
- $results : ResultSetInterface
-
Results to map.
- $locale : string
-
Locale string
Return values
CollectionInterfacesetupAssociations()
Creates the associations between the bound table and every field passed to this method.
protected
setupAssociations() : void
Additionally it creates a i18n HasMany association that will be
used for fetching all translations for each record in the bound table.
unsetEmptyFields()
Unset empty translations to avoid persistence.
protected
unsetEmptyFields(EntityInterface $entity) : void
Should only be called if $this->_config['allowEmptyTranslations'] is false.
Parameters
- $entity : EntityInterface
-
The entity to check for empty translations fields inside.