ShadowTableStrategy
in package
implements
TranslateStrategyInterface
uses
InstanceConfigTrait, LocatorAwareTrait, TranslateStrategyTrait
This class provides a way to translate dynamic data by keeping translations in a separate shadow table where each row corresponds to a row of primary 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.
- addFieldsToQuery() : bool
- Add translation fields to query.
- 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.
- iterateClause() : bool
- Iterate over a clause to alias fields.
- mainFields() : array<string|int, string>
- Lazy define and return the main table fields.
- 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
- Create a hasMany association for all records.
- setupHasOneAssociation() : void
- Create a hasOne association for record with required locale.
- translatedFields() : array<string|int, string>
- Lazy define and return the translation table fields.
- traverseClause() : bool
- Traverse over a clause to alias fields.
- 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' => [], '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
-
Table instance.
- $config : array<string, mixed> = []
-
Configuration.
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|int, mixed> $options) : array<string|int, mixed>
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|int, mixed>
-
The options array used in the marshalling call.
Tags
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, 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
addFieldsToQuery()
Add translation fields to query.
protected
addFieldsToQuery(Query $query, array<string, mixed> $config) : bool
If the query is using autofields (directly or implicitly) add the main table's fields to the query first.
Only add translations for fields that are in the main table, always add the locale field though.
Parameters
- $query : Query
-
The query to check.
- $config : array<string, mixed>
-
The config to use for adding fields.
Return values
bool —Whether a join to the translation table is required.
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.
iterateClause()
Iterate over a clause to alias fields.
protected
iterateClause(Query $query[, string $name = '' ][, array<string, mixed> $config = [] ]) : bool
The objective here is to transparently prevent ambiguous field errors by prefixing fields with the appropriate table alias. This method currently expects to receive an order clause only.
Parameters
- $query : Query
-
the query to check.
- $name : string = ''
-
The clause name.
- $config : array<string, mixed> = []
-
The config to use for adding fields.
Return values
bool —Whether a join to the translation table is required.
mainFields()
Lazy define and return the main table fields.
protected
mainFields() : array<string|int, string>
Return values
array<string|int, string>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()
Create a hasMany association for all records.
protected
setupAssociations() : void
Don't create a hasOne association here as the join conditions are modified in before find - so create/modify it there.
setupHasOneAssociation()
Create a hasOne association for record with required locale.
protected
setupHasOneAssociation(string $locale, ArrayObject $options) : void
Parameters
- $locale : string
-
Locale
- $options : ArrayObject
-
Find options
translatedFields()
Lazy define and return the translation table fields.
protected
translatedFields() : array<string|int, string>
Return values
array<string|int, string>traverseClause()
Traverse over a clause to alias fields.
protected
traverseClause(Query $query[, string $name = '' ][, array<string, mixed> $config = [] ]) : bool
The objective here is to transparently prevent ambiguous field errors by prefixing fields with the appropriate table alias. This method currently expects to receive a where clause only.
Parameters
- $query : Query
-
the query to check.
- $name : string = ''
-
The clause name.
- $config : array<string, mixed> = []
-
The config to use for adding fields.
Return values
bool —Whether a join to the translation table is required.
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.