Register Members List Search Today's Posts Mark Forums Read

Reply
 
Article Options
[How-To] vBulletin API Basics: Variables, Functions, Objects
akanevsky
Join Date: Apr 2005
Posts: 3,972

by akanevsky akanevsky is offline 10 Oct 2005
Rating: (4 votes - 4.75 average)

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.


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

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:


      Block Disabled:      (Update License Status)  
      Suspended or Unlicensed Members Cannot View Code.


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


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  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:


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

    Instead, you should use the following code (which is, obviously, shorter and easier to use):


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  5. DATASTORE ITEMS
    In vBulletin 3.0.x you could commonly see the following code:


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

    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:


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  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:


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • $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.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • 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.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • 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.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • 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.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • function convert_array_to_bits(&$arry, $_FIELDNAMES, $unset = 0);

    Takes an array and returns the bitwise value.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • fetch_template($templatename, $escape = 0, $gethtmlcomments = true);

    Returns a single template from the templatecache or the database.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

    Two most common uses are:


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • vbsetcookie($name, $value = '', $permanent = true);

    Sets a cookie based on vBulletin environmental settings.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • 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.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

  • 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.


    Block Disabled:      (Update License Status)  
    Suspended or Unlicensed Members Cannot View Code.

Sources Used

>> EOD

Last edited by akanevsky; 22 Jun 2013 at 15:10..
Views: 48109
Reply With Quote
Comments
  #2  
Old 10 Oct 2005, 20:00
Kusadasi-Guy Kusadasi-Guy is offline
 
Join Date: May 2004
this is my first subscribed thread (no email notifications).
in other way, i bookmarked.

Thank You so much, DV!
Reply With Quote
  #3  
Old 10 Oct 2005, 23:20
UK Jimbo's Avatar
UK Jimbo UK Jimbo is offline
 
Join Date: Sep 2002
very handy. thanks.
__________________
administrator: visordown.com
Reply With Quote
  #4  
Old 12 Oct 2005, 19:31
waza waza is offline
 
Join Date: Apr 2005
Excellent!!
__________________
Now available: SAPR, it's like god send an angel
Reply With Quote
  #5  
Old 16 Oct 2005, 01:15
Deviation Deviation is offline
 
Join Date: Sep 2005
Real name: Justin
NICE work Dark Visor.
Reply With Quote
  #6  
Old 16 Oct 2005, 13:29
Xtrm2Matt Xtrm2Matt is offline
 
Join Date: Aug 2002
Very nice! Bookmarking for future references

Great job.

Matt
Reply With Quote
  #7  
Old 20 Oct 2005, 22:28
akanevsky akanevsky is offline
 
Join Date: Apr 2005
Real name: Anton Kanevsky
Thanks everyone for feedback.

Tutorial has been updated with two pairs of emendations to the $db class documentation:
- $db->escape_string(); + $db->escape_string_like();
- $db->show_errors(); + $db->hide_errors();
__________________
I can no longer support any of my hacks. Please do not contact me for that. Feel free to create and post new versions of my hacks, as long as you give me credit for the original work.
Reply With Quote
  #8  
Old 02 Nov 2005, 06:22
keithl keithl is offline
 
Join Date: Jul 2005
Brilliant - I've actually bookmarked this thread. Why do Jelsoft make it so bloody difficult for people? I've been looking for some simple software documentation on this type of thing and it's just "not provided".

Many thanks, keep up the good work!

Keith L
Reply With Quote
  #9  
Old 02 Nov 2005, 18:57
eXtremeTim eXtremeTim is offline
 
Join Date: Jun 2002
Real name: Tim Yarbrough
Not bad young grasshoper. Not bad at all.
Reply With Quote
  #10  
Old 02 Nov 2005, 19:01
akanevsky akanevsky is offline
 
Join Date: Apr 2005
Real name: Anton Kanevsky
Not bad young grasshoper. Not bad at all.
Of course
__________________
I can no longer support any of my hacks. Please do not contact me for that. Feel free to create and post new versions of my hacks, as long as you give me credit for the original work.
Reply With Quote
  #11  
Old 02 Nov 2005, 22:40
eXtremeTim eXtremeTim is offline
 
Join Date: Jun 2002
Real name: Tim Yarbrough
Originally Posted by Dark Visor
Of course
I dont need the reference but I will definally pass it on to people im working on training. Since I do php training and vbulletin training for new coders.
Reply With Quote
  #12  
Old 03 Nov 2005, 00:30
akanevsky akanevsky is offline
 
Join Date: Apr 2005
Real name: Anton Kanevsky
Originally Posted by eXtremeTim
I dont need the reference but I will definally pass it on to people im working on training. Since I do php training and vbulletin training for new coders.
No problem, except don't reprint it anywhere...
Pass it on as a link to this thread.
__________________
I can no longer support any of my hacks. Please do not contact me for that. Feel free to create and post new versions of my hacks, as long as you give me credit for the original work.
Reply With Quote
  #13  
Old 03 Nov 2005, 21:27
eXtremeTim eXtremeTim is offline
 
Join Date: Jun 2002
Real name: Tim Yarbrough
Originally Posted by Dark Visor
No problem, except don't reprint it anywhere...
Pass it on as a link to this thread.
You dont have to worry about me reprinting it.

If I was gonna have a vbulletin 3.5 change tutorial on my site I would definatly make my own.
Reply With Quote
  #14  
Old 03 Nov 2005, 21:37
akanevsky akanevsky is offline
 
Join Date: Apr 2005
Real name: Anton Kanevsky
If I was gonna have a vbulletin 3.5 change tutorial on my site I would definatly make my own.
By plagiarising this tutorial? No... I'd prefer that, if you want, reprint it on your site via copy-and-paste method, but leave me my credits and a link to this thread :P Thanks
__________________
I can no longer support any of my hacks. Please do not contact me for that. Feel free to create and post new versions of my hacks, as long as you give me credit for the original work.
Reply With Quote
  #15  
Old 13 Nov 2005, 02:30
Lea Verou Lea Verou is offline
 
Join Date: Jul 2005
Real name: Lea Verou
Originally Posted by Psionic Vision
By plagiarising this tutorial? No... I'd prefer that, if you want, reprint it on your site via copy-and-paste method, but leave me my credits and a link to this thread :P Thanks
Ermm sorry but if I were extremeTim I would get offended with that comment of yours...

Anyway thanks for the great tutorial
Reply With Quote
Reply



Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Article Options

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


New To Site? Need Help?

All times are GMT. The time now is 11:24.

Layout Options | Width: Wide Color: