XenForo Reference Guide for Developer
Back to top  

Model for phrases

Models don't share that much, so most implementations will be adding methods onto this class. This class simply provides helper methods for common actions.

package XenForo_Phrase

 Methods

Constructor.

__construct() 
Inherited

Use create() statically unless you know what you're doing.

inherited_from \XenForo_Model::__construct()

Adds a join to the set of fetch options.

addFetchOptionJoin(array $fetchOptions, integer $join) 
Inherited

Join should be one of the constants.

inherited_from \XenForo_Model::addFetchOptionJoin()

Parameters

$fetchOptions

array

$join

integer

Adds the equivalent of a limit clause using position-based limits.

addPositionLimit(string $table, integer $limit, integer $offset, string $column) : string
Inherited

It no limit value is specified, nothing will be returned.

This must be added within a WHERE clause. If a clause is required, it will begin with "AND", so ensure there is a condition before it.

inherited_from \XenForo_Model::addPositionLimit()

Parameters

$table

string

Name of the table alias to prefix. May be blank for no table reference.

$limit

integer

Number of records to limit to; ignored if <= 0

$offset

integer

Offset from the start of the records. 0+

$column

string

Name of the column that is storing the position

Returns

stringPosition limit clause if needed

Appends the language (phrase) XML for a given add-on to the specified DOM element.

appendPhrasesAddOnXml(\DOMElement $rootNode, string $addOnId) 

Parameters

$rootNode

\DOMElement

$addOnId

string

Ensures that a valid cut-off operator is passed.

assertValidCutOffOperator(string $operator) 
Inherited
inherited_from \XenForo_Model::assertValidCutOffOperator()

Parameters

$operator

string

Builds (and inserts) the phrase map for a specified phrase, from a position within the language tree.

buildPhraseMap(string $title, array $data) 

Parameters

$title

string

Title of the phrase being build

$data

array

Injectable data. Supports languageTree and languagePhraseMap.

Builds the full phrase map data for an entire language sub-tree.

buildPhraseMapForLanguageTree(integer $languageId) : array

Parameters

$languageId

integer

Starting language. This language and all children will be built.

Returns

arrayFormat: [language id][title] => phrase id

Checks that the development directory has been configured and exists

canImportPhrasesFromDevelopment() : boolean

Returns

boolean

Determines if the visiting user can modify a phrase in the specified language.

canModifyPhraseInLanguage(integer $languageId) : boolean

If debug mode is not enabled, users can't modify phrases in the master language.

Parameters

$languageId

integer

Returns

boolean

compileAllPhrases() 

compileAllPhrases($maxExecution, $startLanguage, $startPhrase) 

Parameters

$maxExecution

$startLanguage

$startPhrase

Compiles all phrases in the specified language.

compileAllPhrasesInLanguage($languageId) 

Parameters

$languageId

Compiles and inserts the specified effective phrases.

compileAndInsertEffectivePhrases(array $phrases) 

Parameters

$phrases

array

Array of effective phrase info

Compiles the specified parsed phrase and updates the compiled table and included phrases list.

compileAndInsertParsedPhrase(integer $phraseMapId, string | array $parsedPhrase, string $title, integer $compileLanguageId) 

Parameters

$phraseMapId

integer

The map ID of the phrase being compiled (for includes)

$parsedPhrase

stringarray

Parsed form of the phrase

$title

string

Title of the phrase

$compileLanguageId

integer

Language ID of the phrase

Compiles the list of phrase map IDs and any child phrases that are using the same core phrase.

compileMappedPhrasesInLanguageTree(integer | array $phraseMapIds) : array

Parameters

$phraseMapIds

integerarray

One map ID as a scaler or many as an array

Returns

arrayA list of phrase map IDs that were compiled

Compiles the named phrase in the language tree.

compileNamedPhraseInLanguageTree(string $title, integer $languageId) : array

Any child phrases that use this phrase will be recompiled as well.

Parameters

$title

string

$languageId

integer

Returns

arrayA list of phrase map IDs that were compiled

Compiles the specified phrase data in the language tree.

compilePhraseInLanguageTree(array $parsedRecord) : array

This compiles this phrase in any language that is actually using this phrase.

Parameters

$parsedRecord

array

Full phrase information

Returns

arrayList of phrase map IDs that were compiled

countEffectivePhrasesInLanguage() 

countEffectivePhrasesInLanguage($languageId, array $conditions) 

Parameters

$languageId

$conditions

Factory method to get the named model.

create(string $class) : \XenForo_Model
InheritedStatic

The class must exist or be autoloadable or an exception will be thrown.

inherited_from \XenForo_Model::create()

Parameters

$class

string

Class to load

Returns

\XenForo_Model

Deletes the named master phrase if it exists.

deleteMasterPhrase(string $title, array $options) 

Parameters

$title

string

$options

array

Deletes the named master phrases if they exist.

deleteMasterPhrases(array $phraseTitles, array $options) 

Parameters

$phraseTitles

array

Phrase titles

$options

array

Deletes the phrases that belong to the specified add-on.

deletePhrasesForAddOn(string $addOnId) 

Parameters

$addOnId

string

Fetches results from the database with each row keyed according to preference.

fetchAllKeyed(string $sql, string $key, mixed $bind, string $nullPrefix) : array
Inherited

The 'key' parameter provides the column name with which to key the result. For example, calling fetchAllKeyed('SELECT item_id, title, date FROM table', 'item_id') would result in an array keyed by item_id: [$itemId] => array('item_id' => $itemId, 'title' => $title, 'date' => $date)

Note that the specified key must exist in the query result, or it will be ignored.

inherited_from \XenForo_Model::fetchAllKeyed()

Parameters

$sql

string

SQL to execute

$key

string

Column with which to key the results array

$bind

mixed

Parameters for the SQL

$nullPrefix

string

If the key is null, prefix the counter with this

Returns

array

Finds the necessary phrase map updates for the specified phrase within the sub-tree.

findPhraseMapUpdates(integer $parentId, array $languageTree, array $languagePhraseMap, integer $defaultPhraseId) : array

If {$defaultPhraseId} is non-0, a return entry will be inserted for {$parentId}.

Parameters

$parentId

integer

Parent of the language sub-tree to search.

$languageTree

array

Tree of languages

$languagePhraseMap

array

List of languageId => phraseId pairs for the places where this phrase has been customized.

$defaultPhraseId

integer

The default phrase ID that non-customized phrase in the sub-tree should get.

Returns

arrayFormat: [language id] => [effective phrase id]

Gets all effective phrases in a language.

getAllEffectivePhrasesInLanguage(integer $languageId) : array

"Effective" means a merged/flattened system where every valid phrase has a record.

Parameters

$languageId

integer

Returns

arrayFormat: [] => (array) effective phrase info

Returns all phrases customized in a language in alphabetical title order

getAllPhrasesInLanguage(integer $languageId) : array

Parameters

$languageId

integer

Language ID

Returns

arrayFormat: [title] => (array) language

Gets a list of SQL conditions in the format for a clause.

getConditionsForClause(array $sqlConditions) : string
Inherited

This always returns a value that can be used in a clause such as WHERE.

inherited_from \XenForo_Model::getConditionsForClause()

Parameters

$sqlConditions

array

Returns

string

Gets the specified field from a content type, if specified for that type.

getContentTypeField(string $contentType, string $fieldName) : string | false
Inherited
inherited_from \XenForo_Model::getContentTypeField()

Parameters

$contentType

string

$fieldName

string

Returns

stringfalse

Gets the value of the specified field for each content type that has that field.

getContentTypesWithField(string $fieldName) : array
Inherited
inherited_from \XenForo_Model::getContentTypesWithField()

Parameters

$fieldName

string

Returns

arrayFormat: [content type] => field value

Gets the effective phrase based on a known map idea.

getEffectivePhraseByMapId(integer $phraseMapId) : array | false

Returns all phrase information and the map ID.

Parameters

$phraseMapId

integer

Returns

arrayfalseEffective phrase info.

Gets the effective phrase in a language by its title.

getEffectivePhraseByTitle(string $title, integer $languageId) : array | false

This includes all phrase information and the map ID.

Parameters

$title

string

$languageId

integer

Returns

arrayfalseEffective phrase info.

Get the effective phrase list for a language.

getEffectivePhraseListForLanguage($languageId, array $conditions, array $fetchOptions) : array

"Effective" means a merged/flattened system where every valid phrase has a record.

This only returns data appropriate for a list view (map id, phrase id, title). phrase_state is also calculated based on whether this phrase has been customized. State options: default, custom, inherited.

Parameters

$languageId

$conditions

$fetchOptions

Returns

arrayFormat: [] => (array) phrase list info

Gets the effective phrase value in all languages for the specified list of phrases.

getEffectivePhraseValuesInAllLanguages(array $phraseList) : array

Parameters

$phraseList

array

List of phrases to fetch

Returns

arrayFormat: [language id][title] => value

Gets multiple effective phrases based on 1 or more map IDs.

getEffectivePhrasesByMapIds(\integery | array $phraseMapIds) : array

Returns all phrase information and the map ID.

Parameters

$phraseMapIds

\integeryarray

Either one map ID as a scalar or any array of map IDs

Returns

arrayFormat: [] => (array) effective phrase info

Gets the titles of all phrases that should be cached globally.

getGlobalPhraseCacheTitles() : array

Returns

arrayList of titles

Gets the phrase map information for all phrases that are mapped to the specified phrase ID.

getMappedPhrasesByPhraseId(integer $phraseId) : array

Parameters

$phraseId

integer

Returns

arrayFormat: [] => (array) phrase map info

Gets the value for the named master phrase.

getMasterPhraseValue(string $title) : string

Parameters

$title

string

Returns

stringEmpty string if phrase is value

Gets all the master (language 0) phrases in the specified add-on.

getMasterPhrasesInAddOn(string $addOnId) : array

Parameters

$addOnId

string

Returns

arrayFormat: [title] => info

Gets the specified model object from the cache.

getModelFromCache(string $class) : \XenForo_Model
Inherited

If it does not exist, it will be instantiated.

inherited_from \XenForo_Model::getModelFromCache()

Parameters

$class

string

Name of the class to load

Returns

\XenForo_Model

Gets the order by clause for an SQL query.

getOrderByClause(array $choices, array $fetchOptions, string $defaultOrderSql) : string
Inherited
inherited_from \XenForo_Model::getOrderByClause()

Parameters

$choices

array

$fetchOptions

array

$defaultOrderSql

string

Returns

stringOrder by clause or empty string

Gets all phrases that are outdated (master version edited more recently).

getOutdatedPhrases() : array

Does not include contents of phrase.

Returns

array[phrase id] => phrase info, including master_version_string

Gets mapped phrase information from the parent language of the named phrase.

getParentMappedPhraseByTitle(string $title, integer $languageId) : array | false

If the named language is 0 (or invalid), returns false.

Parameters

$title

string

$languageId

integer

Returns

arrayfalse

Returns the phrase specified by phrase_id

getPhraseById(integer $phraseId) : array | false

Parameters

$phraseId

integer

phrase ID

Returns

arrayfalsephrase

Returns the path to the phrase development directory, if it has been configured and exists

getPhraseDevelopmentDirectory() : string

Returns

stringPath to development directory

Gets language ID/phrase ID pairs for all languages where the named phrase is modified.

getPhraseIdInLanguagesByTitle(string $phraseTitle) : array

Parameters

$phraseTitle

string

Returns

arrayFormat: [language_id] => phrase_id

Fetches a phrase from a particular language based on its title.

getPhraseInLanguageByTitle(string $title, integer $languageId) : array

Note that if a version of the requested phrase does not exist in the specified language, nothing will be returned.

Parameters

$title

string

Title

$languageId

integer

language ID (defaults to master language)

Returns

array

Gets the phrases development XML.

getPhrasesDevelopmentXml() : \DOMDocument

Returns

\DOMDocument

Fetches a phrases from a particular language based on titles.

getPhrasesInLanguageByTitles(array $titles, integer $languageId) : array

Note that if a version of the requested phrase does not exist in the specified language, nothing will be returned for that phrase.

Parameters

$titles

array

List of titles

$languageId

integer

language ID (defaults to master language)

Returns

arrayFormat: [title] => info

Fetch phrases that contain $textSearch and have titles that match $titleConstraint from either the specified language, or the viewing user's chosen language.

getPhrasesMatchingSearchTextWithConstrainedTitles(string $textSearch, string | array $titleConstraint, integer $maxResults, integer | null $languageId, array $viewingUser) : array

Parameters

$textSearch

string

Text to find in phrase

$titleConstraint

stringarray

Either a string to be LIKE lr quoted, or an array containing 0 => search text including wild card, 1 => wild card character

$maxResults

integer

Max results to return

$languageId

integernull

Language in which to search

$viewingUser

array

Viewing user array

Returns

array[title => text]

Imports the master language (phrase) XML for the specified add-on.

importPhrasesAddOnXml(\SimpleXMLElement $xml, string $addOnId, integer $maxExecution, integer $offset) : boolean | integer

Parameters

$xml

\SimpleXMLElement

$addOnId

string

$maxExecution

integer

Maximum run time in seconds

$offset

integer

Number of elements to skip

Returns

booleanintegerTrue on completion; false if the XML isn't correct; integer otherwise with new offset value

Imports all phrases from the phrases directory into the database

importPhrasesFromDevelopment() 

Internal function to import phrase XML.

importPhrasesXml(\SimpleXMLElement $xml, integer $languageId, string | null $addOnId, array $existingPhrases, integer $maxExecution, integer $offset) 

This does not remove any phrases that may conflict; that is the responsibility of the caller.

Parameters

$xml

\SimpleXMLElement

Root XML node; must have "phrase" children

$languageId

integer

Target language ID

$addOnId

stringnull

Add-on the phrases belong to; if null, read from xml

$existingPhrases

array

Existing phrases; used to detect and resolve conflicts

$maxExecution

integer

Maximum run time in seconds

$offset

integer

Number of elements to skip

Inserts or updates a master (language 0) phrase.

insertOrUpdateMasterPhrase(string $title, string $text, string $addOnId, array $extra, array $options) 

Errors will be silently ignored.

Parameters

$title

string

$text

string

$addOnId

string

$extra

array

Extra fields to set

$options

array

Inserts or updates an array of master (language 0) phrases.

insertOrUpdateMasterPhrases(array $phrases, string $addOnId, array $extra, array $options) 

Errors will be silently ignored.

Parameters

$phrases

arrayarray

Key-value pairs of phrases to insert/update

$addOnId

string

Add-on all phrases belong to

$extra

array

Extra fields to set

$options

array

Inserts the phrase map records for all elements of various languages.

insertPhraseMapForLanguages(array $languageMapList, boolean $truncate) 

Parameters

$languageMapList

array

Format: [language id][title] => phrase id

$truncate

boolean

If true, all map data is truncated (quicker that way)

Applies a limit clause to the provided query if a limit value is specified.

limitQueryResults(string $query, integer $limit, integer $offset) : string
Inherited

If the limit value is 0 or less, no clause is applied.

inherited_from \XenForo_Model::limitQueryResults()

Parameters

$query

string

SQL query to run

$limit

integer

Number of records to limit to; ignored if <= 0

$offset

integer

Offset from the start of the records. 0+

Returns

stringQuery with limit applied if necessary

Use this to map any phrases that have been inserted directly into the phrase table without the phrase DataWriter being involved.

mapUnhandledPhrases() 

Prepares the limit-related fetching options that can be applied to various queries.

prepareLimitFetchOptions(array $fetchOptions) : array
Inherited

Includes: limit, offset, page, and perPage.

inherited_from \XenForo_Model::prepareLimitFetchOptions()

Parameters

$fetchOptions

array

Unprepared options

Returns

arrayLimit options; keys: limit, offset

preparePhraseConditions() 

preparePhraseConditions(array $conditions, array $fetchOptions) 

Parameters

$conditions

$fetchOptions

Prepares state related fetch limits, based on the list of conditions.

prepareStateLimitFromConditions(array $fetchOptions, string $table, string $stateField, string $userField) : string
Inherited

Looks for keys "deleted" and "moderated".

inherited_from \XenForo_Model::prepareStateLimitFromConditions()

Parameters

$fetchOptions

array

$table

string

Name of the table to prefix the state and user fields with

$stateField

string

Name of the field that holds the state

$userField

string

Name of the field that holds the user ID

Returns

stringSQL condition to limit state

Renames a master phrase.

renameMasterPhrase(string $oldName, string $newName, array $options) 

If you get a conflict, it will be silently ignored.

Parameters

$oldName

string

$newName

string

$options

array

Renames a list of master phrases.

renameMasterPhrases(array $phraseMap, array $options) 

If you get a conflict, it will be silently ignored.

Parameters

$phraseMap

array

Format: [old name] => [new name]

$options

array

Reset an entry or the entire local cache.

resetLocalCacheData($name) 
Inherited

This can be used if you know when some cached data has expired.

inherited_from \XenForo_Model::resetLocalCacheData()

Parameters

$name

Sets whether we're allowed to read values from the cache on a model-level.

setAllowCachedRead(boolean $allowCachedRead) 
Inherited

This may be controllable on an individual level basis, if the implementation allows it.

inherited_from \XenForo_Model::setAllowCachedRead()

Parameters

$allowCachedRead

boolean

Injects a local cache value.

setLocalCacheData(string $name, $value) 
Inherited

This should only be used if you know what you're doing or for testing purposes!

Note that you cannot get the existing data via the public interface. If you think you need the set data, use a new object. It defaults to empty. :)

inherited_from \XenForo_Model::setLocalCacheData()

Parameters

$name

string

$value

Standardizes a set of node permissions and a user ID to always have appropriate data.

standardizeNodePermissionsAndUserId(integer $nodeId, array | null $permissions, integer | null $userId) 
Inherited

If an invalid permission set or user ID is provided, the current visitor's will be used.

inherited_from \XenForo_Model::standardizeNodePermissionsAndUserId()

Parameters

$nodeId

integer

Node permissions are for

$permissions

arraynull

Permissions for node or null to use current visitor's permissions

$userId

integernull

User permissions belong to or null to use current visitor

Standardizes a permission combination and user ID to always have appropriate data.

standardizePermissionCombinationIdAndUserId(integer | null $permissionCombinationId, integer | null $userId) 
Inherited

If null, users current visitor's values.

inherited_from \XenForo_Model::standardizePermissionCombinationIdAndUserId()

Parameters

$permissionCombinationId

integernull

Permission combination ID or null to use current visitor

$userId

integernull

User permissions belong to or null to use current visitor

Standardizes a set of permissions and a user ID to always have appropriate data.

standardizePermissionsAndUserId(array | null $permissions, integer | null $userId) 
Inherited

If an invalid permission set or user ID is provided, the current visitor's will be used.

inherited_from \XenForo_Model::standardizePermissionsAndUserId()

Parameters

$permissions

arraynull

Global pPermissions or null to use current visitor's permissions

$userId

integernull

User permissions belong to or null to use current visitor

Standardizes a viewing user reference array.

standardizeViewingUserReference(array $viewingUser) 
Inherited

This array must contain all basic user info (preferably all user info) and include global permissions in a "permissions" key. If not an array or missing a user_id, the visitor's values will be used.

inherited_from \XenForo_Model::standardizeViewingUserReference()

Parameters

$viewingUser

arraynull

Standardizes the viewing user reference for the specific node.

standardizeViewingUserReferenceForNode(integer $nodeId, array $viewingUser, array $nodePermissions) 
Inherited
inherited_from \XenForo_Model::standardizeViewingUserReferenceForNode()

Parameters

$nodeId

integer

$viewingUser

arraynull

Viewing user; if null, use visitor

$nodePermissions

arraynull

Permissions for this node; if null, use visitor's

Helper to unserialize permissions in a list of items.

unserializePermissionsInList(array $items, string $serializedKey, string $targetKey) : array
Inherited
inherited_from \XenForo_Model::unserializePermissionsInList()

Parameters

$items

array

List of items

$serializedKey

string

Key where serialized permissions are

$targetKey

string

Key where unserialized permissions will go

Returns

arrayList of items with permissions unserialized

Internal handler to build the phrase map data for a language sub-tree.

_buildPhraseMapForLanguageTree(integer $languageId, array $map, array $languages, array $languageTree) : array

Calls itself recursively.

Parameters

$languageId

integer

Language to build (builds children automatically)

$map

array

Base phrase map data. Format: [title] => phrase id

$languages

array

List of languages

$languageTree

array

Language tree

Returns

arrayFormat: [language id][title] => phrase id

Helper method to get the cache object.

_getCache(boolean $forceCachedRead) : \Zend_Cache_Core | \Zend_Cache_Frontend | false
Inherited

If cache reads are disabled, this will return false.

inherited_from \XenForo_Model::_getCache()

Parameters

$forceCachedRead

boolean

If true, the global "allow cached read" value is ignored

Returns

\Zend_Cache_Core\Zend_Cache_Frontendfalse

Gets the data registry model.

_getDataRegistryModel() : \XenForo_Model_DataRegistry
Inherited
inherited_from \XenForo_Model::_getDataRegistryModel()

Returns

\XenForo_Model_DataRegistry

Helper method to get the database object.

_getDb() : \Zend_Db_Adapter_Abstract
Inherited
inherited_from \XenForo_Model::_getDb()

Returns

\Zend_Db_Adapter_Abstract

_getLanguageModel() 

_getLanguageModel() : \XenForo_Model_Language

Returns

\XenForo_Model_Language

Gets the named entry from the local cache.

_getLocalCacheData(string $name) : mixed
Inherited
inherited_from \XenForo_Model::_getLocalCacheData()

Parameters

$name

string

Returns

mixed

 Properties

 

$_allowCachedRead : boolean
Inherited

If not, it should be retrieved from the source.

inherited_from \XenForo_Model::$$_allowCachedRead
 

$_cache : \Zend_Cache_Core | \Zend_Cache_Frontend
Inherited
inherited_from \XenForo_Model::$$_cache
 

$_db : \Zend_Db_Adapter_Abstract
Inherited
inherited_from \XenForo_Model::$$_db
 

$_localCacheData : array
Inherited

This data is generally treated as canonical, even if {$_allowCachedRead} is false.

inherited_from \XenForo_Model::$$_localCacheData
 

$_modelCache : array
Inherited
inherited_from \XenForo_Model::$$_modelCache