Go Back   vb.org Archive > vBulletin Article Depository > Read An Article > vBulletin 3 Articles
Reload this Page [How-To] vBulletin API Basics: Variables, Functions, Objects
FAQ Members List Calendar Search Today's Posts Mark Forums Read

Reply
Page 5 of 5 « First 34 5
 
Thread Tools
[How-To] vBulletin API Basics: Variables, Functions, Objects
akanevsky
Join Date: Apr 2005
Posts: 3,972

 

Show Printable Version Email this Page Subscription
akanevsky akanevsky is offline 10-09-2005, 10:00 PM
vBulletin API Basics: Variables, Functions, Objects

This How-To should serve as a reference to coders, who have a basic knowledge of PHP and who want to make their own mods.

$vbulletin (Type: Object)

Contains vBulletin data that has been in separate variables in vB 3.0.x.
Below you can find a translation table of changed variables and functions.
This is an expanded version of the list that you can find in vBulletin's source code (functions_legacy.php).
vBulletin 3.0.3 locations are on the left hand side, and the corresponding vBulletin 3.5.0 locations are on the right hand side.
Legacy locations can be enabled by running legacy_enable(), although this is officially not recommended for long term compatibility.

Code:
* $vboptions['x']                            --> $vbulletin->options['x']
* $iforumcache                               --> $vbulletin->iforumcache
* $forumcache                                --> $vbulletin->forumcache
* $usergroupcache                            --> $vbulletin->usergroupcache
* $datastore['wol_spiders']                  --> $vbulletin->wol_spiders
* $smiliecache                               --> $vbulletin->smiliecache
* $stylechoosercache                         --> $vbulletin->stylecache
* $datastore['x']                            --> $vbulletin->x
* $bbuserinfo['x']                           --> $vbulletin->userinfo['x']
* $session['x']                              --> $vbulletin->session->vars['x']
*
* $_BITFIELD['usergroup']                    --> $vbulletin->bf_ugp
* $_BITFIELD['usergroup']['x']               --> $vbulletin->bf_ugp_x
* $_BITFIELD['usergroup']['x']['y']          --> $vbulletin->bf_ugp_x['y']
* $_BITFIELD['calmoderatorpermissions']['x'] --> $vbulletin->bf_misc_calmoderatorpermissions['x']
* $_BITFIELD['moderatorpermissions']['x']    --> $vbulletin->bf_misc_moderatorpermissions['x']
* $_BITFIELD['languageoptions']['x']         --> $vbulletin->bf_misc_languageoptions['x']
* $_USEROPTIONS['x']                         --> $vbulletin->bf_misc_useroptions['x']
* $_FORUMOPTIONS['x']                        --> $vbulletin->bf_misc_forumoptions['x']
* $_INTPERMS                                 --> $vbulletin->bf_misc_intperms
* $_INTPERMS['x']                            --> $vbulletin->bf_misc_intperms['x']
*
* ------------------------------------------------------------------------------
* Variables and Functions below are NOT affected/re-enabled by legacy_enable()
* ------------------------------------------------------------------------------
*
* $_GET/$_POST/$_REQUEST/$_COOKIE/$_FILES    --> $vbulletin->GPC['x']
* $DB_Site->x()                              --> $vbulletin->db->x()
* $url                                       --> $vbulletin->url
* $nozip                                     --> $vbulletin->nozip
* $script                                    --> $vbulletin->script
* $scriptpath                                --> $vbulletin->scriptpath
*
* HTML_SELECTED                              --> not defined anymore in vB 3.5
* HTML_CHECKED                               --> not defined anymore in vB 3.5
*
* bbcode_parse()                             --> $bbcode_parser->parse
* iif($condition, $r_true, $r_false)         --> obsolete, use ($condition ? $r_true : $r_false) instead;
Please note the following:
  1. $vbulletin
    Inside of object classes, you should access $vbulletin->[...] as $this->registry->[...]. Therefore, use that structure when modifying code inside of any classes.
    .
  2. VARIABLES ENABLED FOR TEMPLATES
    $vboptions['x'], $bbuserinfo['x'] and $session['x'] do work in the template system without running legacy_enable().
    .
  3. SUPERGLOBALS
    $_GET/$_POST/$_REQUEST/$_COOKIE/$_FILES/$_SERVER/$_ENV are available anywhere, but generally you should avoid using them. Instead, "clean" those variables and place them into $vbulletin->GPC using $vbulletin->input->clean_gpc() and $vbulletin->input->clean_array_gpc() methods.
    You can read more about these two "cleaning" methods here.

    As a summary:
    1. Use $vbulletin->input->clean_gpc() for a single variable, and $vbulletin->input->clean_array_gpc() for arrays.
    2. After variables are patched through, they can be accessed using $vbulltin->GPC (which is an array).
    3. Cleaning 'somevar' will not create variable $somevar.
    4. $vbulletin->input->clean_gpc() returns the clean value, therefore the following code will work out nicely:

      Code:
      $id = $vbulletin->input->clean_gpc('r', 'id', TYPE_UINT);

    Once you get to know the syntax of those functions, you can use the following as a reference:

    Code:
    ------------------------------------
SOURCES AND THEIR EQUIVALENTS
------------------------------------

'g'                    - $_GET
'p'                    - $_POST
'r'                    - $_REQUEST
'c'                    - $_COOKIE
's'                    - $_SERVER
'e'                    - $_ENV
'f'                    - $_FILES

------------------------------------
VALID DATA TYPES
------------------------------------

TYPE_BOOL              - Boolean
TYPE_INT               - Integer
TYPE_UINT              - Unsigned Integer
TYPE_NUM               - Floating Point Number
TYPE_UNUM              - Unsigned Floating Point Number
TYPE_UNIXTIME          - Unix Timestamp (Unsigned Integer)
TYPE_STR               - Trimmed String (No leading or trailing whitespace)
TYPE_NOTRIM            - String
TYPE_NOHTML            - Trimmed String sent through htmlspecialchars_uni()
TYPE_ARRAY             - Array
TYPE_FILE              - File
TYPE_NOCLEAN           - Unvalidated
  4. GLOBALIZING VARIABLES IN FUNCTIONS
    Since most of the variables can be found within the $vbulletin class, there is generally no need to globalize more than one variable (which is $vbulletin). An exception would be the $vbphrase array, which currently cannot be found within the $vbulletin class.

    Taking the above account, the following code is not good:

    Code:
    function foo()
{
    global $forumcache, $vbulletin, $vboptions;

    $forumcache =& $vbulletin->forumcache;
    $vboptions =& $vbulletin->options;

    foreach ($forumcache AS $forumid => $forum)
    {
        if ($vboptions['something'])
        {
            // do stuff
        }
    }
}
    Instead, you should use the following code (which is, obviously, shorter and easier to use):

    Code:
    function foo()
{
    global $vbulletin;

    foreach ($vbulletin->forumcache AS $forumid => $forum)
    {
        if ($vbulletin->options['something'])
        {
            // do something
        }
    }
}
  5. DATASTORE ITEMS
    In vBulletin 3.0.x you could commonly see the following code:

    PHP Code:
    if (isset($datastore_item)) 
    Unfortunately, this does not work in vBulletin 3.5.0, since the datastore items are now contained within $vbulletin class.
    You need to use the following code instead:

    PHP Code:
    if ($vbulletin->datastore_item !== null) 
  6. BITFIELDS
    In case you have been wondering, "ugp" stands for "UserGroup Permissions".
    To avoid the confusing "$object->array[key1][key2][key3][key4]...[key10]" stuff, there are references set up that allow you to talk to deep elements quickly. For example, $vbulletin->bf_ugp_adminpermissions is a reference to $vbulletin->bf_ugp['adminpermissions'].
    .
  7. BBCODE PARSE
    BBCode Parser has changed slightly in vBulletin 3.5.
    To familiarize yourself with the new syntax, check out KirbyDE's How-To.
    .
  8. MISCELLANEOUS
    It is impossible to list here every aspect of vBulletin code, therefore you should familizarize yourself with the contents of init.php and class_core.php before beginning to hack into the system (and I know you are in a rush ).

$db (Type: Object)

As you might have judged from the Table 1 in this tutorial, the database object in vB3.5 is $vbulletin->db.
However, $db is another way to access that object; it is the way that used everywhere unless you call it from within a function. In functions, use $vbulletin->db.
Obviously, the purpose of the database method is to perform various operations on the database. Most common methods are described below.
  • $db->query();
    Deprecated in favor of below methods (to save memory).
    Returns: MySQL Resource
    .
  • $db->query_read();
    Performs SELECT and SHOW operations only.
    These queries will execute on the slave server, if one is defined.
    Returns: MySQL Resource
    .
  • $db->query_write();
    Performs INSERT, REPLACE, UPDATE, DROP, ALTER and other data-modifying queries.
    These queries will execute on the master server.
    Returns: MySQL Resource
    .
  • $db->query_first();
    Same as query_read(), but returns first result as an array.
    Returns: array on success / boolean false on failure
    .
  • $db->num_rows($mysql_resource_var);
    Input: A MySQL resource variable (usually output of the first three methods).
    Returns: int Amount of Resulting Rows
    .
  • $db->fetch_array($mysql_resource_var);
    Input: A MySQL resource variable (usually output of the first three methods).
    Returns: array One row from the mysql results on success / boolean false on failure

    To fetch each row consecutively, use the following code:

    Code:
    while ($var = $db->fetch_array($mysql_resource_var))
{
	// your code ($var contains the array);
}
  • $db->insert_id();
    Input: None.
    Returns: int Row ID of the latest INSERT operation.
    .
  • $db->escape_string(); and $db->escape_string_like();
    Input: String.
    Returns: string A string with appropriate characters escaped.

    These two functions must be used instead of the PHP built-in addslashes() and addslashes_like().
    Using the PHP built-in functions may cause problems on non-MySQL systems.
    .
  • $db->show_errors(); and $db->hide_errors();
    Input: None.
    Returns: None.

    The first function enables sql error output (default), whereas the second function disables such output.
    Useful when you do not want the script to die on error (example: no die on product installation if a table already exists).

Data Managers

Data Managers (DMs) are an interface to various data objects used within vBulletin. They enforce necessary constraints and administrator-set options on the data to ensure that the data is valid.
You can read more about Data Managers in vBulletin's online manual.
Also, you can read specifically about the User DM in this KirbyDE's How-To, and about Thread DM here.

Authentication Storage

The authentication data is stored in the following way (thank to Kirby for this info):

$_COOKIE:
{cookiepfx}userid - plain(userid)
{cookiepfx}password - md5(md5(md5('PlaintextPassword') . salt) . 'LicenseNo').

TABLE user:
password - md5(md5('PlaintextPassword') . salt)

Note that for cookie, {cookiepfx} is your board's cookie prefix. It is configurable via admincp and is accessible via the COOKIE_PREFIX constant.

Important Functions
  • construct_page_nav($pagenumber, $perpage, $results, $address, $address2 = '');

    Returns the HTML for multi-page navigation.
    Two latest arguments are not used yet, therefore they are not documented.

    Code:
    $pagenumber	int     Total number of items found
$perpage        string  Base address for links eg: showthread.php?t=99{&page=4}
$results        string  Ending portion of address for links
  • eval(standard_error(fetch_error('error_phrase')));

    Outputs a standard error message with a phrase of your choice.
    fetch_error looks up the phrase you specify in the "Front-End Error Messages" phrase category.
    Error phrases must be prefixed with "error_".
    .
  • print_standard_redirect($redir_phrase, $doquery = true, $forceredirect = false);

    Returns eval()-able code to initiate a standard redirect
    $vbulletin->url should contain the target url for the redirect.

    Code:
    $redir_phrase	string   Name of redirect phrase
$doquery        boolean  If true, it will fetch $redir_phrase from "Front-End Redirect Messages" phrase category. Must be prefixed with "redirect_".
                         If false, it will use the value of $redir_phrase as the phrase itself.
$forceredirect  boolean  Should generally be set to true.
  • is_valid_email($email);

    Checks an email for validity and returns true or false.
    .
  • can_moderate($forumid = 0, $do = '', $userid = -1, $usergroupids = '');

    Checks whether a user can moderate a certain forum.

    Code:
    $forumid       int       Specific forum to check. If not set, will check whether the user is a moderator of any forum at all.
$do            string    Specific mod action to check. If not set, will check whether the user is a moderator of the forum specified in $forumid.
$userid        int       User ID to check. If not set, will use $vbulletin->userinfo.
$usergroupids  string    List of group IDs, separate by commas, to which the user belongs. Should be generally left blank.
  • can_administer();

    Checks whether or not the visiting user has administrative permissions

    This function can optionally take any number of parameters, each of which
    should be a particular administrative permission you want to check. For example:
    can_administer('canadminsettings', 'canadminstyles', 'canadminlanguages')
    If any one of these permissions is met, the function will return true.
    If no parameters are specified, the function will simply check that the user is an administrator.
    .
  • convert_bits_to_array(&$bitfield, $_FIELDNAMES);

    Converts a bitfield into an array of 1 / 0 values based on the array describing the resulting fields. Returns an array.

    Code:
    &$bitfield      int      (ref) Bitfield
$_FIELDNAMES    array     Array containing field definitions - array('canx' => 1, 'cany' => 2, 'canz' => 4) etc.
  • function convert_array_to_bits(&$arry, $_FIELDNAMES, $unset = 0);

    Takes an array and returns the bitwise value.

    Code:
    &arry           array     Array for input.
$_FIELDNAMES    array     Array containing field definitions - array('canx' => 1, 'cany' => 2, 'canz' => 4) etc.
$unset          int       Defines whether to unset the array data once it has been converted to bits
  • fetch_template($templatename, $escape = 0, $gethtmlcomments = true);

    Returns a single template from the templatecache or the database.

    Code:
    $templatename    string   Name of template to be fetched
$escape          int      Escape quotes in template? 1: escape; -1: unescape; 0: do nothing
$gethtmlcomments boolean  Wrap template in HTML comments showing the template name?
    Two most common uses are:

    Code:
    eval('$mycustomvar .= "' . fetch_template('mycustomtemplate') . '";');
eval('print_output("' . fetch_template('mycustomtemplate') . '");');
  • vbsetcookie($name, $value = '', $permanent = true);

    Sets a cookie based on vBulletin environmental settings.

    Code:
    $name           string    Cookie name
$value          mixed     Value to store in the cookie
$permanent      boolean   If true, do not set an expiry date for the cookie
  • vb_number_format($number, $decimals = 0, $bytesize = false, $decimalsep = null, $thousandsep = null);

    Formats a number with user's own decimal and thousands chars and returns the formatted number.

    Code:
    $number          mixed     Number to be formatted: integer / 8MB / 16 GB / 6.0 KB / 3M / 5K / ETC
$decimals        integer   Number of decimal places to display
$bytesize        boolean   Special case for byte-based numbers
$decimalsep      string    Custom decimal separator (to override user's preference) 
$thousandsep     string    Custom thousands separator (to override user's preference)
  • vbmail($toemail, $subject, $message, $notsubscription = false, $from = '', $uheaders = '', $username = '');

    Starts the process of sending an email - either immediately or by adding it to the mail queue.

    Code:
    $toemail          string     Destination email address
$subject          string     Email message subject
$message	  string     Email message body
$notsubscription  boolean    If true, do not use the mail queue and send immediately
$from             string     Optional name/email to use in 'From' header
$uheaders         string     Additional headers
$username         string     Username of person sending the email
Sources Used

>> EOD
Reply With Quote
  #42  
Old 05-14-2008, 03:41 AM
Lea Verou Lea Verou is offline
 
Join Date: Jul 2005
Location: Greece
Posts: 1,856
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Its a pity such articles don't get written any more and we have to read the 3.5 ones...
Reply With Quote
  #43  
Old 05-15-2008, 03:54 PM
akanevsky akanevsky is offline
 
Join Date: Apr 2005
Posts: 3,972
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
It's true, you'll find that most of the things in the article are true for 3.6 as well as 3.7.
Reply With Quote
  #44  
Old 05-15-2008, 11:57 PM
Lea Verou Lea Verou is offline
 
Join Date: Jul 2005
Location: Greece
Posts: 1,856
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Quote:
Originally Posted by Psionic Vision View Post
It's true, you'll find that most of the things in the article are true for 3.6 as well as 3.7.
I know, but I wanted to mention that such good articles don't get written any more...
Reply With Quote
  #45  
Old 05-16-2008, 12:14 AM
Adrian Schneider's Avatar
Adrian Schneider Adrian Schneider is offline
 
Join Date: Jul 2004
Posts: 2,528
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
There isn't much point in adding too many more vB. articles as everything has pretty much been covered. If you are looking for general programming articles, then this isn't the best place.
Reply With Quote
  #46  
Old 05-16-2008, 12:22 AM
Lea Verou Lea Verou is offline
 
Join Date: Jul 2005
Location: Greece
Posts: 1,856
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Quote:
Originally Posted by SirAdrian View Post
There isn't much point in adding too many more vB. articles as everything has pretty much been covered. If you are looking for general programming articles, then this isn't the best place.
I think that there are a lot of things to be covered...

And no, I'm not looking for general programming articles here. In fact I find that comment of yours quite offending.
Reply With Quote
  #47  
Old 05-16-2008, 12:25 AM
Adrian Schneider's Avatar
Adrian Schneider Adrian Schneider is offline
 
Join Date: Jul 2004
Posts: 2,528
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
It's not supposed to be offensive, sorry if you found it that way.

This is from a perspective of someone who would be writing the articles.
Reply With Quote
  #48  
Old 05-21-2008, 01:28 PM
Antivirus's Avatar
Antivirus Antivirus is offline
 
Join Date: Sep 2004
Location: Black Lagoon
Posts: 1,090
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Aside from vb's AJAX being migrated to the Yahoo UI, I'm not really aware of that much which has changed from 3.6 to 3.7 either. Most of the time whjen I am coding and need to reference things, the articles which are still here seem to do the trick for me.
Reply With Quote
  #49  
Old 01-08-2010, 04:45 AM
CypherSTL CypherSTL is offline
 
Join Date: Mar 2006
Location: St. Charles, MO
Posts: 306
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Doing some upgrading on a few mods, and was wondering how I can check the actual version of vBulletin itself.

Basically, if Less Than 4.0, run this, else, run this.
Reply With Quote
  #50  
Old 10-02-2010, 08:22 PM
sonixax sonixax is offline
 
Join Date: Sep 2010
Posts: 28
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Hmmm , how can i set "variable portions" in my own Product ?
Reply With Quote
Reply
Page 5 of 5 « First 34 5

« Previous Thread | Next Thread »
Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts
BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Forum Jump


All times are GMT. The time now is 07:09 PM.

Contact Us - Archive - Top

Powered by vBulletin® Version 3.8.12 by vBS
Copyright ©2000 - 2024, vBulletin Solutions Inc.
X vBulletin 3.8.12 by vBS Debug Information
  • Page Generation 0.05988 seconds
  • Memory Usage 2,330KB
  • Queries Executed 24 (?)
More Information
Template Usage:
  • (1)SHOWTHREAD
  • (1)ad_footer_end
  • (1)ad_footer_start
  • (1)ad_header_end
  • (1)ad_header_logo
  • (1)ad_navbar_below
  • (1)ad_showthread_beforeqr
  • (16)bbcode_code
  • (2)bbcode_php
  • (2)bbcode_quote
  • (1)footer
  • (1)forumjump
  • (1)forumrules
  • (1)gobutton
  • (1)header
  • (1)headinclude
  • (1)modsystem_article
  • (1)navbar
  • (4)navbar_link
  • (120)option
  • (1)pagenav
  • (1)pagenav_curpage
  • (2)pagenav_pagelink
  • (10)post_thanks_box
  • (1)post_thanks_box_bit
  • (10)post_thanks_button
  • (1)post_thanks_javascript
  • (1)post_thanks_navbar_search
  • (1)post_thanks_postbit
  • (10)post_thanks_postbit_info
  • (9)postbit
  • (10)postbit_onlinestatus
  • (10)postbit_wrapper
  • (1)spacer_close
  • (1)spacer_open
  • (1)tagbit_wrapper 
Phrase Groups Available:
  • global
  • inlinemod
  • postbit
  • posting
  • reputationlevel
  • showthread
Included Files:
  • ./showthread.php
  • ./global.php
  • ./includes/init.php
  • ./includes/class_core.php
  • ./includes/config.php
  • ./includes/functions.php
  • ./includes/class_hook.php
  • ./includes/modsystem_functions.php
  • ./includes/functions_bigthree.php
  • ./includes/class_postbit.php
  • ./includes/class_bbcode.php
  • ./includes/functions_reputation.php
  • ./includes/functions_post_thanks.php 
Hooks Called:
  • init_startup
  • init_startup_session_setup_start
  • init_startup_session_setup_complete
  • cache_permissions
  • fetch_threadinfo_query
  • fetch_threadinfo
  • fetch_foruminfo
  • style_fetch
  • cache_templates
  • global_start
  • parse_templates
  • global_setup_complete
  • showthread_start
  • showthread_getinfo
  • forumjump
  • showthread_post_start
  • showthread_query_postids
  • showthread_query
  • bbcode_fetch_tags
  • bbcode_create
  • showthread_postbit_create
  • postbit_factory
  • postbit_display_start
  • post_thanks_function_post_thanks_off_start
  • post_thanks_function_post_thanks_off_end
  • post_thanks_function_fetch_thanks_start
  • fetch_musername
  • post_thanks_function_fetch_thanks_end
  • post_thanks_function_thanked_already_start
  • post_thanks_function_thanked_already_end
  • post_thanks_function_fetch_thanks_bit_start
  • post_thanks_function_show_thanks_date_start
  • post_thanks_function_show_thanks_date_end
  • post_thanks_function_fetch_thanks_bit_end
  • post_thanks_function_fetch_post_thanks_template_start
  • post_thanks_function_fetch_post_thanks_template_end
  • postbit_imicons
  • bbcode_parse_start
  • bbcode_parse_complete_precache
  • bbcode_parse_complete
  • postbit_display_complete
  • post_thanks_function_can_thank_this_post_start
  • pagenav_page
  • pagenav_complete
  • tag_fetchbit_complete
  • forumrules
  • navbits
  • navbits_complete
  • showthread_complete