vB_Api_Phrase
extends vB_Api
in package
vB_Api_Phrase
Tags
Table of Contents
- $controller : string
- API Controller
- $db : vB_Database
- Database object.
- $disabled : bool
- Indicates whether the API was disabled
- $disableFalseReturnOnly : array<string|int, mixed>
- Contains white listed methods which return a false response when API is disabled in special scenarios like forum closed, password expiry, ip ban and others.
- $disableWhiteList : array<string|int, mixed>
- Contains white listed methods which act as normal when API is disabled no matter of special scenarios like forum closed, password expiry, ip ban and others.
- $library : vB_Library_Phrase
- $phrasecache : mixed
- $shortcode_replace_map : mixed
- $styles : mixed
- $instances : mixed
- $instancesRaw : array<string|int, mixed>
- We want API subclasses to access the instances only through getters
- $vb4_input_mappings : mixed
- $wrappers : mixed
- __serialize() : mixed
- __sleep() : mixed
- __unserialize() : mixed
- __wakeup() : mixed
- callNamed() : The
- Call the given api function by name with a named arguments list.
- checkApiState() : mixed
- This method checks whether the API method is enabled.
- clearCache() : mixed
- Clears all previously loaded API objects.
- clearPhraseCache() : mixed
- Clears the phrase cache, needed primarily for unit test.
- delete() : void
- Delete a phrase
- fetch() : array<string|int, mixed>
- Fetch phrases
- fetch_phrasetypes() : array<string|int, mixed>
- Fetches an array of existing phrase types from the database
- fetchByGroup() : array<string|int, mixed>
- Fetch phrases by group
- fetchEmailPhrases() : array<string|int, mixed>
- Returns message and subject for an email.
- fetchOrphans() : array<string|int, mixed>
- Fetch orphan phrases
- fetchPrivateMessagePhrases() : array<string|int, mixed>
- Returns message and subject for sending a private message (would also work for notifications if needed)
- findUpdates() : array<string|int, mixed>
- Find custom phrases that need updating
- getApiClassName() : mixed
- getLanguageid() : array<string|int, mixed>
- Fetch the "best" languageid in the order of current session's languageid, the default languageid from datastore, or the master languageid (-1).
- getPhrases() : array<string|int, mixed>
- Fetch raw phrases
- instance() : vB_Api
- Returns an instance of the API object which translates exceptions to an array Use this method for API clients.
- instanceInternal() : vB_Api
- Returns an instance of the API object which doesn't handle exceptions This should only be used in other API objects, not for clients of the API
- map_vb4_input_to_vb5() : string
- Returns vb5 api method name.
- map_vb5_errors_to_vb4() : mixed
- Alters the error array in any way necessary to interface correctly with vb4.
- map_vb5_output_to_vb4() : mixed
- Alters the output array in any way necessary to interface correctly with vb4.
- processOrphans() : void
- Process orphan phrases
- renderPhrases() : array<string|int, mixed>
- Returns rendered phrases from phrase strings and/or data
- renderPhrasesNoShortcode() : array<string|int, mixed>
- Returns rendered phrases from phrase strings and/or data
- replace() : void
- Find and replace phrases in languages
- replaceShortcodesInString() : string
- Replaces {shortcodes} in a string
- save() : standard
- Add a new phrase or update an existing phrase
- search() : array<string|int, mixed>
- Search phrases
- __construct() : mixed
- checkHasAdminPermission() : none
- Determines if the calling user has the given admin permission, and if not throws an exception
- checkHasPermission() : none
- Determines if the calling user has the given bitfield permission, and if not, throws a 'no_permission' exception.
- checkIsLoggedIn() : mixed
- Determines if the calling user has the given admin permission, and if not throws an exception
- getApiClass() : mixed
- getApiClassNameInternal() : mixed
- hasAdminPermission() : bool
- Determines if the calling user has the given admin permission
- inDebugMode() : mixed
- isDisableFalseReturnOnly() : bool
- Checks if method returns false response only when API is disabled.
- isWhiteListed() : bool
- Checks if method is white listed when API is disabled.
- parsePhrases() : array<string|int, mixed>
- Handled output from query from fetch() and fetchByGroup()
- setController() : mixed
- Set controller
- cms_vb4_to_vb5_method_mapping() : mixed
- convertPhraseText() : string
- Convert phrase text to sprintf format
- default_vb4_to_vb5_method_mapping() : mixed
- doShortcodeReplacements() : mixed
- hasAdminPermissionInternal() : mixed
- Internal function to power the previous cover functions
- remove_nulls() : mixed
- renderPhrase() : mixed
- renderPhrasesInternal() : mixed
- wrapLoggerIfNeeded() : mixed
- Wrap the api object with the log wrapper class if needed.
Properties
$controller
API Controller
protected
string
$controller
$db
Database object.
protected
vB_Database
$db
$disabled
Indicates whether the API was disabled
protected
bool
$disabled
= alse
$disableFalseReturnOnly
Contains white listed methods which return a false response when API is disabled in special scenarios like forum closed, password expiry, ip ban and others.
protected
array<string|int, mixed>
$disableFalseReturnOnly
= array()
$disableWhiteList
Contains white listed methods which act as normal when API is disabled no matter of special scenarios like forum closed, password expiry, ip ban and others.
protected
array<string|int, mixed>
$disableWhiteList
= array('fetch', 'getPhrases')
$library
protected
vB_Library_Phrase
$library
$phrasecache
protected
mixed
$phrasecache
= array()
$shortcode_replace_map
protected
mixed
$shortcode_replace_map
= array()
$styles
protected
mixed
$styles
= array()
$instances
private
static mixed
$instances
$instancesRaw
We want API subclasses to access the instances only through getters
private
static array<string|int, mixed>
$instancesRaw
$vb4_input_mappings
private
static mixed
$vb4_input_mappings
= array(
'blog.post_comment' => array('method' => 'vb4_blog.post_comment'),
'blog.post_postcomment' => array('method' => 'vb4_blog.post_postcomment'),
'blog.post_updateblog' => array('method' => 'vb4_blog.post_updateblog'),
'blog.post_newblog' => array('method' => 'vb4_blog.post_newblog'),
'blog.post_editblog' => array('method' => 'vb4_blog.post_editblog'),
'blog_list' => array('method' => 'vb4_blog.bloglist'),
'api_init' => array('method' => 'api.init'),
'api_cmssectionlist' => array('method' => 'Vb4_Cms.sectionlist'),
'api_cmscategorylist' => array('method' => 'Vb4_Cms.categorylist'),
/*
// These can no longer be mapped directly to vB_Api_User::login/logout
// due to additional processing of devicetoken that may be required
// for mapi calls.
'login_login' => array(
'method' => 'user.login',
'request_mappings' => array(
'vb_login_username' => 'username',
'vb_login_password' => 'password',
'vb_login_md5password' => 'md5password',
'vb_login_md5password_utf' => 'md5passwordutf'
)
),
'login_logout' => array(
'method' => 'user.logout'
),
*/
'get_vbfromfacebook' => array('method' => 'vb4_facebook.getVbfromfacebook'),
)
$wrappers
private
static mixed
$wrappers
Methods
__serialize()
public
__serialize() : mixed
Return values
mixed —__sleep()
public
__sleep() : mixed
Return values
mixed —__unserialize()
public
__unserialize(mixed $serialized) : mixed
Parameters
- $serialized : mixed
Return values
mixed —__wakeup()
public
__wakeup() : mixed
Return values
mixed —callNamed()
Call the given api function by name with a named arguments list.
public
callNamed() : The
Used primarily to translate REST requests into API calls.
Return values
The —return of the method or an error if the method doesn't exist, or is static, a constructor or destructor, or otherwise shouldn't be callable as and API method. It is also an error if the value of a paramater is not provided and that parameter doesn't have a default value.
checkApiState()
This method checks whether the API method is enabled.
public
checkApiState(mixed $method) : mixed
For extensions check make sure $controller property is already set.
Parameters
- $method : mixed
Return values
mixed —clearCache()
Clears all previously loaded API objects.
public
static clearCache() : mixed
Intended for use in tests where the loading pattern can cause issues with objects that cache thier own data.
Return values
mixed —clearPhraseCache()
Clears the phrase cache, needed primarily for unit test.
public
clearPhraseCache() : mixed
Return values
mixed —delete()
Delete a phrase
public
delete(int $phraseid) : void
Parameters
- $phraseid : int
-
Pharse ID to be deleted
Return values
void —fetch()
Fetch phrases
public
fetch(array<string|int, mixed> $phrases[, int $languageid = NULL ]) : array<string|int, mixed>
Parameters
- $phrases : array<string|int, mixed>
-
An array of phrase ID to be fetched
- $languageid : int = NULL
-
Language ID. If not set, it will use current session's languageid, if passed a 0, use the current user/forum default language.
Tags
Return values
array<string|int, mixed> —-- phraseid => phrase value
fetch_phrasetypes()
Fetches an array of existing phrase types from the database
public
fetch_phrasetypes([mixed $doUcFirst = false ]) : array<string|int, mixed>
Parameters
- $doUcFirst : mixed = false
Return values
array<string|int, mixed> —fetchByGroup()
Fetch phrases by group
public
fetchByGroup(mixed $groups[, int $languageid = NULL ]) : array<string|int, mixed>
Parameters
- $groups : mixed
- $languageid : int = NULL
-
Language ID. If not set, it will use current session's languageid
Return values
array<string|int, mixed> —Phrase' texts
fetchEmailPhrases()
Returns message and subject for an email.
public
fetchEmailPhrases(string $email_phrase[, array<string|int, mixed> $email_vars = array() ][, array<string|int, mixed> $emailsub_vars = array() ], int $languageid[, string $emailsub_phrase = '' ]) : array<string|int, mixed>
This does NOT insert the {shortcode} substitutions, that is done in the mail send() function where we know the recipient's username, etc.
Parameters
- $email_phrase : string
-
Name of email phrase to fetch
- $email_vars : array<string|int, mixed> = array()
-
Variables for the email message phrase
- $emailsub_vars : array<string|int, mixed> = array()
-
Variables for the email subject phrase
- $languageid : int
-
Language ID from which to pull the phrase (see fetch_phrase $languageid) note that 0 means forum default language while null means the language for the current user. The former is the better default for this function because we rarely send email to the current user. However we should really be passing that in consistantly.
- $emailsub_phrase : string = ''
-
If not empty, select the subject phrase with the given name
Return values
array<string|int, mixed> —fetchOrphans()
Fetch orphan phrases
public
fetchOrphans() : array<string|int, mixed>
Return values
array<string|int, mixed> —Orphan phrases
fetchPrivateMessagePhrases()
Returns message and subject for sending a private message (would also work for notifications if needed)
public
fetchPrivateMessagePhrases(int $userid, string $email_phrase[, array<string|int, mixed> $email_vars = array() ][, array<string|int, mixed> $emailsub_vars = array() ], int $languageid[, string $emailsub_phrase = '' ]) : array<string|int, mixed>
This inserts the {shortcode} substitutions.
This is intended to be a replacement for fetchEmailPhrases() and should be used in its place when the phrases are going to be used for a notification or private message sent within vBulletin. fetchEmailPhrases() should be used when sending an actual email. The function signature is the same with the exception of $userid as the first parameter, done this way since it is not optional.
Parameters
- $userid : int
-
User ID of the recipient of the message.
- $email_phrase : string
-
Name of email phrase to fetch
- $email_vars : array<string|int, mixed> = array()
-
Variables for the email message phrase
- $emailsub_vars : array<string|int, mixed> = array()
-
Variables for the email subject phrase
- $languageid : int
-
Language ID from which to pull the phrase (see fetch_phrase $languageid) note that 0 means forum default language while null means the language for the current user. The former is the better default for this function because we rarely send email to the current user. However we should really be passing that in consistantly.
- $emailsub_phrase : string = ''
-
If not empty, select the subject phrase with the given name
Return values
array<string|int, mixed> —findUpdates()
Find custom phrases that need updating
public
findUpdates() : array<string|int, mixed>
Return values
array<string|int, mixed> —Updated phrases
getApiClassName()
public
static getApiClassName(mixed $controller) : mixed
Parameters
- $controller : mixed
Return values
mixed —getLanguageid()
Fetch the "best" languageid in the order of current session's languageid, the default languageid from datastore, or the master languageid (-1).
public
getLanguageid([bool $getCharset = false ]) : array<string|int, mixed>
This is the languageid that's used by fetch().
Parameters
- $getCharset : bool = false
-
(Optional) true to also return charset of current languageid. Default false.
Return values
array<string|int, mixed> —'languageid' => languageid used for current session's phrases
getPhrases()
Fetch raw phrases
public
getPhrases(array<string|int, mixed> $phrases[, int $languageid = NULL ]) : array<string|int, mixed>
Note that these are not suitable for display to the user as is since many phrases have placeholders and this will not substitute them. It is available in situations where the client expects to render the phrases itself (particularly in situations where the phrase can be cached and reused client side).
Parameters
- $phrases : array<string|int, mixed>
-
An array of phrase ID to be fetched
- $languageid : int = NULL
-
Language ID. If not set, it will use current session's languageid, if passed a 0, use the current user/forum default language.
Return values
array<string|int, mixed> —-- 'phrases' -- array(phraseid => phrase value)
instance()
Returns an instance of the API object which translates exceptions to an array Use this method for API clients.
public
static instance(string $controller[, bool $refresh_cache = false ]) : vB_Api
Parameters
- $controller : string
-
-- name of the API controller to load
- $refresh_cache : bool = false
-
-- true if we want to force the cache to update with a new api object primarily intended for testing
Return values
vB_Api —instanceInternal()
Returns an instance of the API object which doesn't handle exceptions This should only be used in other API objects, not for clients of the API
public
static instanceInternal(string $controller[, bool $refresh_cache = false ]) : vB_Api
Parameters
- $controller : string
-
-- name of the API controller to load
- $refresh_cache : bool = false
-
-- true if we want to force the cache to update with a new api object primarily intended for testing
Return values
vB_Api —map_vb4_input_to_vb5()
Returns vb5 api method name.
public
static map_vb4_input_to_vb5(string $method, array<string|int, mixed> &$request) : string
May alter request array.
Parameters
- $method : string
-
-- vb4 method name
- $request : array<string|int, mixed>
-
-- $_REQUEST array for this api request
Return values
string —map_vb5_errors_to_vb4()
Alters the error array in any way necessary to interface correctly with vb4.
public
static map_vb5_errors_to_vb4(string $method, array<string|int, mixed> &$data) : mixed
Parameters
- $method : string
-
-- vb4 method name
- $data : array<string|int, mixed>
-
-- error array from vb5
Return values
mixed —map_vb5_output_to_vb4()
Alters the output array in any way necessary to interface correctly with vb4.
public
static map_vb5_output_to_vb4(string $method, array<string|int, mixed> &$data) : mixed
Parameters
- $method : string
-
-- vb4 method name
- $data : array<string|int, mixed>
-
-- output array from vb5
Return values
mixed —processOrphans()
Process orphan phrases
public
processOrphans(array<string|int, mixed> $del, array<string|int, mixed> $keep) : void
Parameters
- $del : array<string|int, mixed>
-
Orphan phrases to be deleted. In format array('varname@fieldname') will also accept url encoded array('varname%40fieldname')
- $keep : array<string|int, mixed>
-
Orphan phrases to be kept -- array of phraseids.
Return values
void —renderPhrases()
Returns rendered phrases from phrase strings and/or data
public
renderPhrases(mixed $phrases[, mixed $languageid = null ]) : array<string|int, mixed>
Parameters
- $phrases : mixed
- $languageid : mixed = null
Return values
array<string|int, mixed> —'phrases' => array('key' => rendered phrase)
renderPhrasesNoShortcode()
Returns rendered phrases from phrase strings and/or data
public
renderPhrasesNoShortcode(mixed $phrases[, mixed $languageid = null ]) : array<string|int, mixed>
In some circumstances, primarily email, we need to defer shortcode replacement because we need to handle things for a user other than the current logged in user (many of the shortcodes are user specific). This allows us to do that.
Parameters
- $phrases : mixed
- $languageid : mixed = null
Return values
array<string|int, mixed> —'phrases' => array('key' => rendered phrase)
replace()
Find and replace phrases in languages
public
replace(array<string|int, mixed> $replace, string $searchstring, string $replacestring, int $languageid) : void
Parameters
- $replace : array<string|int, mixed>
-
A list of phrase ID to be replaced
- $searchstring : string
-
Search string
- $replacestring : string
-
Replace string
- $languageid : int
-
Language ID
Return values
void —replaceShortcodesInString()
Replaces {shortcodes} in a string
public
replaceShortcodesInString(mixed $string) : string
The phrase API might not be the best place for this function, since it just replaces shortcodes in an arbitrary string. But these shortcodes are mostly associated with phrases, so it makes the most sense right now. It also simplifies things, as we can reuse the doShortcodeReplacements function.
Parameters
- $string : mixed
Return values
string —The string with the {shortcodes} replaced with their corresponding values.
save()
Add a new phrase or update an existing phrase
public
save(string $fieldname, string $varname, array<string|int, mixed> $data) : standard
Parameters
- $fieldname : string
-
New Phrase Type for adding, old Phrase Type for editing
- $varname : string
-
New Varname for adding, old Varname for editing
- $data : array<string|int, mixed>
-
Phrase data to be added or updated 'text' => Phrase text array. 'oldvarname' => Old varname for editing only 'oldfieldname' => Old fieldname for editing only 't' => 'ismaster' => 'product' => Product ID of the phrase
Return values
standard —success array
search()
Search phrases
public
search(array<string|int, mixed> $criteria) : array<string|int, mixed>
Parameters
- $criteria : array<string|int, mixed>
-
Criteria to search phrases. It may have the following items: 'searchstring' => Search for Text 'searchwhere' => Search in: 0 - Phrase Text Only, 1 - Phrase Variable Name Only, 2 - Phrase Text and Phrase Variable Name 'casesensitive' => Case-Sensitive 1 - Yes, 0 - No 'exactmatch' => Exact Match 1 - Yes, 0 - No 'languageid' => Search in Language. The ID of the language 'phrasetype' => Phrase Type. Phrase group IDs to search in. 'transonly' => Search Translated Phrases Only 1 - Yes, 0 - No 'product' => Product ID to search in.
Return values
array<string|int, mixed> —Phrases
__construct()
protected
__construct() : mixed
Return values
mixed —checkHasAdminPermission()
Determines if the calling user has the given admin permission, and if not throws an exception
protected
checkHasAdminPermission(string|array<string|int, mixed> $adminPermission) : none
Checks for:
- A valid CP Session
- The passed adminpermission.
Parameters
- $adminPermission : string|array<string|int, mixed>
-
The admin permission to check. If an array then the check passes if the user has any of the permissions given.
Tags
Return values
none —checkHasPermission()
Determines if the calling user has the given bitfield permission, and if not, throws a 'no_permission' exception.
protected
checkHasPermission(string $group, string $permission) : none
Parameters
- $group : string
-
The permission group where the permission is located
- $permission : string
-
The permission to check
Tags
Return values
none —checkIsLoggedIn()
Determines if the calling user has the given admin permission, and if not throws an exception
protected
checkIsLoggedIn() : mixed
Return values
mixed —getApiClass()
protected
static getApiClass(mixed $controller[, mixed $errorCheck = true ]) : mixed
Parameters
- $controller : mixed
- $errorCheck : mixed = true
Return values
mixed —getApiClassNameInternal()
protected
static getApiClassNameInternal(mixed $controller) : mixed
Parameters
- $controller : mixed
Return values
mixed —hasAdminPermission()
Determines if the calling user has the given admin permission
protected
hasAdminPermission(string|array<string|int, mixed> $adminPermission) : bool
Useful if you need to know if the calling user but do not care why they do not have that permission. Generally useful if there is a behavior difference between admins and non admins, but the call can be processed for either.
Parameters
- $adminPermission : string|array<string|int, mixed>
-
The admin permission to check. If an array then the check passes if the user has any of the permissions given.
Return values
bool —true if checks pass, false otherwise
inDebugMode()
protected
inDebugMode() : mixed
Return values
mixed —isDisableFalseReturnOnly()
Checks if method returns false response only when API is disabled.
protected
isDisableFalseReturnOnly(mixed $method) : bool
Parameters
- $method : mixed
Return values
bool —Indicates whether method returns false response only.
isWhiteListed()
Checks if method is white listed when API is disabled.
protected
isWhiteListed(mixed $method) : bool
Parameters
- $method : mixed
Return values
bool —Indicates whether method is or is not a white list.
parsePhrases()
Handled output from query from fetch() and fetchByGroup()
protected
parsePhrases(mixed $phrasesdata[, mixed $phrases = array() ][, mixed $languageid = -1 ]) : array<string|int, mixed>
Parameters
- $phrasesdata : mixed
- $phrases : mixed = array()
- $languageid : mixed = -1
Return values
array<string|int, mixed> —Phrases phrases
setController()
Set controller
protected
setController(mixed $controller) : mixed
Parameters
- $controller : mixed
Return values
mixed —cms_vb4_to_vb5_method_mapping()
private
static cms_vb4_to_vb5_method_mapping(mixed $method, mixed &$request) : mixed
Parameters
- $method : mixed
- $request : mixed
Return values
mixed —convertPhraseText()
Convert phrase text to sprintf format
private
static convertPhraseText(string $text) : string
Parameters
- $text : string
Return values
string —default_vb4_to_vb5_method_mapping()
private
static default_vb4_to_vb5_method_mapping(mixed $method) : mixed
Parameters
- $method : mixed
Return values
mixed —doShortcodeReplacements()
private
doShortcodeReplacements(mixed $phrases[, mixed $userid = null ]) : mixed
Parameters
- $phrases : mixed
- $userid : mixed = null
Return values
mixed —hasAdminPermissionInternal()
Internal function to power the previous cover functions
private
hasAdminPermissionInternal(mixed $adminPermission) : mixed
@param string|array $adminPermission The admin permission to check. If an array
then the check passes if the user has any of the permissions given.
Parameters
- $adminPermission : mixed
Return values
mixed —remove_nulls()
private
static remove_nulls(mixed &$data) : mixed
Parameters
- $data : mixed
Return values
mixed —renderPhrase()
private
renderPhrase(mixed $phrasestring, mixed $args) : mixed
Parameters
- $phrasestring : mixed
- $args : mixed
Return values
mixed —renderPhrasesInternal()
private
renderPhrasesInternal(mixed $phrases, mixed $languageid, mixed $doShortcodes) : mixed
Parameters
- $phrases : mixed
- $languageid : mixed
- $doShortcodes : mixed
Return values
mixed —wrapLoggerIfNeeded()
Wrap the api object with the log wrapper class if needed.
private
static wrapLoggerIfNeeded(mixed $controller, mixed $api_object) : mixed
Parameters
- $controller : mixed
- $api_object : mixed