vBulletin 5.6.5 API

vB_Api_Phrase extends vB_Api
in package

vB_Api_Phrase

Tags
access

public

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

$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')

$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
deprecated

-- use renderPhrases or getPhrases depending on if you

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 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
throws
inlinemodauth_required

-- The current session is not a mod/admin session

throws
nopermission_loggedin

-- The user does not have the given permission

throws
no_permission

-- The user is not logged in at all.

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
throws
no_permission
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
Return values
mixed

Search results