Will78
29-Jan-2006, 09:19 AM
In previous versions of IPB, different classes were instantiated into separate objects. You may remember $ibforums, $print, $std...all of these were separate objects that had to be globalized in each function that you wished to use them in.
In 2.1, most of the same properties and methods are still available, however you will access them through $this->ipsclass instead (in 99% of the instances in which you will need to know this).
$ipsclass is instantiated in index.php, and a reference to it is passed to each object that is created. Let's take a look at some of the properties and methods available, as well as the objects you can access through $ipsclass.
$this->ipsclass->DB->function_name()
The old $DB has been moved to $this->ipsclass->DB. Just about all of the functions have retained the same name as was used in 2.0, so you should mostly be able to just update $DB to $this->ipsclass->DB in your files and be good to go. Just remember you don't have to globalize anything now since you have the pseudo-variable $this to use.
$this->ipsclass->print->function_name()
The old $print has been moved to $this->ipsclass->print. Most of the calls are the same, so you have little changes to make here as well.
$this->ipsclass->ip_address
Contains the IP address of the current viewer. Uses the settings in the ACP regarding the matching of X_FORWARDED_FOR IP addresses.
$this->ipsclass->vars['variable_name']
All those variables that are added to the system cache (mostly the default settings available upon installation of the board, but modifications can be set to be added to the system cache as well) will be stored in this array. Replace 'variable_name' with the key you used to add the setting. You can take a look at the settings available in this array by going into the ACP->Tools & Settings->Cache Control and hit the button next to settings, and hit View Cache. You'll get a popup window with the array printed out.
$this->ipsclass->cache['cache_store_key']
You can add entries to the forums_cache_store table, and then load them up when your page is called (either through your file under sources/components_init/, or by adding the key to the $choice array in index.php). The cache_store_key will be the cs_key in forums_cache_store. If you set the record in the database to be an array (cs_array=1), then the array will be unserialized and stored here. Thus, you can access it through $this->ipsclass->cache['cs_key']['value_in_array'].
$this->ipsclass->member['array_value']
This is the data for the current member.
Note: You should be using 'members_display_name' from this array to get the current user's name, rather than the 'name' value. This is the case as of 2.1.0.
Note that not EVERY column from forums_members is stored here. Also note that nearly all columns from forums_groups are stored in this array, and an additional 'is_mod' key is set to a 1 or a 0, depending upon whether the member is a moderator or not.
$this->ipsclass->input['form_or_url_value']
This array holds all GET and POST keys (merged, POST overwrites GET) already cleaned and ready for use. As a modification author, it is still always your responsibility to code with security in mind, however common "baddies" are removed from these keys and values (such as ' " < and > characters).
$this->ipsclass->time_options
$this->ipsclass->num_format
$this->ipsclass->get_magic_quotes
$this->ipsclass->query_string_safe
$this->ipsclass->query_string_real
$this->ipsclass->user_agent
$this->ipsclass->browser
$this->ipsclass->operating_system
$this->ipsclass->can_use_fancy_js
Stores some properties for the script to access. Time options is used when calling get_date(), as is num_format. get_magic_quotes stores the current setting of get_magic_quotes_gpc(). Query string safe is a "safe" formatted query string with & entities, while query_string_real contains the actual query string with &.
The user agent, browser and OS are stored in the next three properties.
can_use_fancy_js is determined if the user has a compatible version of Mozilla or IE that will allow the AJAX-type and RTE javascript functions to work. Support for other browsers will likely be added as they adopt the specifications.
$this->ipsclass->init_load_cache( [array] )
You pass an array of cs_key values. The function loads them into $this->ipsclass->cache['cs_keys'] (cs_keys being the keys you pass to the function). You should attempt to load your cache when this function is first called (using the components_init/ plugin style, or by specifying the keys to load in index.php if you add a new "act=" page, as each call to this function will result in an additional (unnecessary) database query.
$this->ipsclass->init_db_connection()
Initilizes database connection based on the configuration settings currently set. There should be very few times you need to call this manually, as it has already been done for you in index.php.
$this->ipsclass->fetch_os()
Again, few times you should need to use this, as this function is called automatically and the result is stored in $this->ipsclass->operating_system. Return values include "mac", "windows", and "unknown".
$this->ipsclass->fetch_browser()
Another function you should not have to spend much time learning. The value is already stored in $this->ipsclass->browser as an array. Keys are 'browser' and 'version'.
$this->ipsclass->load_class( string var, string var, [string var] )
This function, while useful, is commonly not used. This function loads a class. First argument is the file name (including path information). The second argument is the class name. If you have a constructor function in the class (PHP 5, ___construct(), or PHP 4, function with same name as class name) that accepts an argument, you can pass it the argument through this function as well. The third argument this function accepts is an optional argument you wish to pass to the class you are loading.
$this->ipsclass->can_queue_posts( [string var] )
This function determines if this user can manager queued posts. The optional argument is a forum id (if you wish to check a specific forum).
$this->ipsclass->get_multimod( string var )
Checks if a user can use the multi-mod tool, and if so returns an array of allowed actions (based on their privileges set in the ACP). The argument is required, and is the forum id to check against.
$this->ipsclass->unpack_member_cache( array )
While not exactly *required*, if the serialized array is not passed to this function it will serve no purpose. This function is designed to take a serialized array and return it unserialized.
$this->ipsclass->pack_and_update_member_cache( int var, array, [array] )
This function stores the members cache (in forums_members.members_cache). The int you pass to it is the member id (probably most often $this->ipsclass->member['id']). The first array (required) is the array you would like to store in this members members_cache record. The last (optional) array is the existing cache record. This is required, however if you do not pass this array to the function, it will load the member's existing cache record for you.
The two arrays are merged and the resulting array is serialized and stored back in the members table.
Really there should be just about no times when you need to use this function.
$this->ipsclass->update_forum_cache()
Updates the forum cache, just as indicated. Unlike the other caches, you do not need to populate $this->ipsclass->cache['forum_cache'], as this function will do it for you when it is called.
$this->ipsclass->update_cache( array )
Updates the record in the forums_cache_store table. The array accepts 'name', 'value', 'array', 'deletefirst', and 'donow'. deletefirst and donow are flags to tell the function whether to first delete the record, and then store a new one (versus updating an existing record), and the donow flag indicates if the cache should be updated when this function is called, or just flagged to be updated on shutdown.
The name is the cs_key. The array key is a flag to indicate if the value is an array or not. Arrays are serialized before they are stored (and automatically unserliazed with the init_load_cache function). The value is the value to be stored. You can optionally NOT pass the value, and store it in $this->ipsclass->cache[ 'name' ] (where name is the name you pass to the function). This function will automatically use that value if none is passed.
Common usage is to store statistics or something similar that you don't want to have to generate on the fly on each page load. When it is time to update the value, you update the value in $this->ipsclass->cache['keyname']['value'] and the entire array (or single value) is available in your script immediately, plus the update_cache function will have access to it as well. Either way works.
$this->ipsclass->my_deconstructor()
deconstructor function. Runs miscellaneous stored database queries, closes database connection, and sends any pending emails stored through the process_mail_que function).
$this->ipsclass->process_mail_queue()
Sends queued emails in increments. This function is called on each page load (on shutdown) processing remaining emails.
$this->ipsclass->acp_load_template( string var )
Loads a template file to be used in the ACP (file should be located under skin_acp/IPB2_Standard/acp_skin_html). You can first set $this->ipsclass->skin_acp to be a different directory and IPB2_Standard will be replaced with the directory you specified.
$this->ipsclass->acp_load_language( string var )
Loads a language file to be used in the ACP. Language abstraction for the ACP is expected in 3.0, however this has not been finalized.
$this->ipsclass->load_template( string var, [int var] )
Loads a skin template. Loads all functions in the skin template into $this->ipsclass['compiled_templates'][ $name ]->template_function_name( args ). Note: $name is the name you pass in the first argument to this function, and template_function_name( args ) are the functions in this template. Args is optional, depending upon what your skin template requires.
The second parameter is an id, and will force the function to load the skin id specified rather than (necessarily) the current skin set id for the browsing user. Some other properties are set at this time (such as $this->ipsclass->loaded_templates and $this->ipsclass->skin['_type']).
$this->ipsclass->load_skin()
Loads a skin set. Accepts no arguments, loads the skin set based on the members skin choice or the board default (or a forum-specific skin, when applicable). Set's the $this->ipsclass['_skin'] properties.
$this->ipsclass->load_language( string var )
Loads a language file based on the user's default language set (or the board's default language set, if the user has not specified a language set, or only one is available). The required argument is the language file name (without .php at the end).
$this->ipsclass->get_new_pm_notification( [int var, [int var]] )
The first optional parameter is the limit (how many you would like to pull). The second is a flag to specify if this is an XML AJAX request or a standard request. This returns the fully formatted new pm notification box html and is claled (by default) from class_display.php
$this->ipsclass->txt_convert_charsets( string var, string var, [string var] )
This function converts between character sets. Quite nifty. The first argument is the text to convert. The second argument is the character set we are converting FROM. The third argument is the character set to convert to. If this is not passed, the default character set specified in the ACP is used.
This function will try to first use the php function 'mb_convert_encoding', then 'recode_string', followed by 'iconv'. If it is unable to use any of those functions it simply returns the text you passed it. This means you are responsible for ensuring the text is actually converted.
$this->ipsclass->txt_truncate( string var, [int var] )
Truncates a string without breaking html entities. The first argument is the string (likely html formatted), the second argument is the position to truncate to. Default is 30 characters.
$this->ipsclass->txt_alphanumerical_clean( string var )
Returns an alphanumeric only string.
$this->ipsclass->txt_mb_strlen( string var )
Returns the size/length of a multi-byte string.
$this->ipsclass->txt_stripslashes( string var )
Takes into account $this->ipsclass->get_magic_quotes and determines how to properly strip the slashes off of the string. Returns a string with extra slashes stripped.
$this->ipsclass->txt_raw2form( string var )
Takes a string and formats it so it is safe to use in a textarea.
$this->ipsclass->txt_form2raw( string var)
Unconverts text for use in a textarea (specifically, the $ and \ characters).
$this->ipsclass->txt_safeslashes( string var )
Attempt to safely slash the data for input into a database.
$this->ipsclass->txt_htmlspecialchars( string var )
Convert some of the common html entities, includes multi-byte character support.
$this->ipsclass->txt_UNhtmlspecialchars( string var )
Opposite of last function, unconverts the entities the txt_htmlspecialchars converted, includes multi-byte character support.
$this->ipsclass->txt_windowstounix( string var )
Converts Windows (\r\n) (and Mac (\r) ) newlines to Unix newlines.
$this->ipsclass->return_md5_check()
Creates an md5 hash that can be used to validate form input and such. The md5 hash is generated based on some static factors so that an identical hash can be created later and compared to the first hash. Common usage is to add this hash into a form, and then check it when the form is submitted.
$this->ipsclass->trim_leading_comma( string var )
Trims the leading comma of a string.
$this->ipsclass->trim_trailing_comma( string var )
Trims the trailing comma of a string.
$this->ipsclass->clean_comma( string var )
Removes duplicate commas (more than one in a sequence). Useful if you are imploding an array into a comma separated string and the possibility of blank array values existed.
$this->ipsclass->clean_perm_string( string var )
This is a wrapper for the other 3 comma functions. Calls the other three functions for you (so you can make one function call instead of 3 separate ones in your script).
$this->ipsclass->math_strlen_to_bytes( int val )
Converts strlen value to bytes.
$this->ipsclass->size_format( int val )
Converts a size (in bytes) to a human readable size with KB or MB at the end (or bytes, if it is less than 1 kb).
$this->ipsclass->print_forum_rules( int val )
When passed the one (required) argument, this function prints the forum rules for the forum id passed. The returned value is fully formatted based on the html template used.
$this->ipsclass->hdl_ban_line( array )
Pass this function an array with unit, and timespan set, or pass this function a time in format date_start:date_end:timespan:unit and a ban timeframe is returned.
$this->ipsclass->check_perms( array )
You must first set $this->ipsclass->perm_id_array with your permission array. Then you pass the user's set permission array, and a TRUE/FALSE comparison is done to determine if the user is permitted or not. Your script would be responsible for stopping the user if FALSE is returned.
$this->ipsclass->create_perms_from_group( string var )
This function accepts a comma separated string of group ids, and then returns a comma separated string of permission mask ids associated with those groups.
$this->ipsclass->do_number_format( int val )
Formats a number based on settings specified in the ACP for number formatting.
$this->ipsclass->hdl_forum_read_cookie( [string val])
Sets/gets a cookie specifying the forums this user has read.
$this->ipsclass->scale_image( array )
Array should contain 'max_width', 'max_height', 'cur_width', and 'cur_height. The function returns an array with 'img_height' and 'img_width' set. The values should proportionately resize the image so that it falls within the maximum settings you sent.
$this->ipsclass->show_gif_img( int val )
Generates and displays a random number as an image for the anti-spam controls.
$this->ipsclass->show_gd_img( int val )
Same as above, only using GD (which is harder for bots/scripts to analyze and return the actual values from).
$this->ipsclass->my_nl2br( string var )
Passed a string, this function will turn new lines into XHTML br tags.
$this->ipsclass->my_br2nl( string var )
Does the opposite of the last function, turning br tags into newlines.
$this->ipsclass->make_profile_link( string var, [int val] )
You pass this function a name and an id, and it returns a profile link (based on the input values). This function does not verify if the data is accurate. It only verifies the id is > 0 and returns a link if it is, else just the name.
$this->ipsclass->boink_it( string val )
The input string should be a (valid) url. This function will use your setting in the ACP to determine the type of redirect to utilize. Location headers (or Refresh headers on Windows) are optimal, however this function supports a "meta redirect" in case some of your php files are outputting white space causing the headers not to work.
$this->ipsclass->make_password()
Returns a random 8 character password.
$this->ipsclass->folder_icon( array, [int val], [int val] )
This function is designed to determine the appopriate topic folder icon. You pass this function the topic information in the array, set the second argument to 1/0 depending upon if you were the topic starter, and optionally send the time you wish to compare against (last_visit time is used if this is ommitted), and this function determines which icon is appropriate to display.
$this->ipsclass->text_tidy( string val )
Takes raw text from a database and converts to all html entities. Uses the html entity translation, as well as some regular expression matching to try to convert everything for a textarea (or for storage, theoretically). This function does not check if characters have already been html converted, thus it would turn & into &amp;. Use this function at your own risk.
$this->ipsclass->build_pagelinks( array )
One of my favorite functions, this is a simple, yet powerful one. It builds page links, that's it. But it saves you the trouble of having to determine how many records were on each page, and where did you start at, and how many are left and so forth.
You pass this function an array with the following keys set appropriate:
leave_out (number of pages to show to each side of current page before adding the ...)
USE_ST (whether to set the page start number at st= or something customized...this is the record your user is starting at, typically used in your querie's limit cause to produce LIMIT {perpage},{st})
TOTAL_POSS (the number of total records)
PER_PAGE (how many records per page)
CUR_ST_VAL (current value of st=, or your custom start value point)
BASE_URL (the base url to append to...this should be a full url, containing any search or other parameters...num and st will be appended to indicate the current record you are at, and how many per page you are viewing)
L_SINGLE (the string to display if only a single page is recorded)
$this->ipsclass->build_forum_jump( int val, [int val, [int val]])
Builds the forum jump list, taking into account whether you set the option enable short forum jump list in the acp or not. The first argument specifies whether the full html should be returned or not (you may not want all the html if you are making your own drop down, or making a multi-select). The second flag overrides the short forum jump list setting, and the third flag removes redirect forums from the list.
$this->ipsclass->clean_email( string val )
Verifies an email address and returns TRUE or FALSE depending upon whether it appears to be valid.
$this->ipsclass->get_date( string val, string val, [int val, [int val]] )
This function will accept a timestamp in the first argument, and a method (in the valid list of methods found under the property time_options discussed above), and format it into a readable date based on the method requested. The third argument forces removal of relative dates (today, yesterday), and the fourth argument is to specify if you do wish to use relative dates. It is override within the function, so there is no point passing it. Takes into account your date settings in the ACP, as well as the members and boards time zone offsets.
$this->ipsclass->get_time( string val, string val )
This is similar to get date except that the second argument is a date() compliant method of formatting a timestamp into a date. The first argument is still the timestamp. Time zone settings are *not* taken into account.
$this->ipsclass->get_time_offset()
Returns the current users applied time zone offset in minutes (which will be the board time zone offset if none is specified).
$this->ipsclass->convert_local_date_to_unix( array )
Pass in an array with hour, minute, month, day, year specified and a timestamp is returned (minus the offset that is returned automatically from get_time_offset()).
$this->ipsclass->unixstamp_to_human( string val )
Accepts a timestamp and returns an array with minute, hour, day, month, and year set appropriately.
$this->ipsclass->date_gmmktime( int val, int val, int val, int val, int val, int val )
Nearly identical to gmmktime().
$this->ipsclass->date_getgmdate( string val )
Nearly identical to getdate().
$this->ipsclass->my_setcookie( string val, string val, [int val] )
Sets a cookie (first argument) with value (second argument) based on cookie settings in ACP. The third optional parameter specifies if it should be a stickie cookie (not expire anytime in the near future).
$this->ipsclass->my_getcookie( string val )
Returns the cookie specified by the input name. If you use my_setcookie, then on another page load you can use my_getcookie to obtain the value originally set.
$this->ipsclass->parse_incoming()
Called automatically, this populates $this->ipsclass->input (and calls the functions to clean the keys and values for you).
$this->ipsclass->parse_clean_key( string val )
Takes the string value input and cleans it for usage as an array key.
$this->ipsclass->parse_clean_value( string val )
Parses the value sent to this function and cleans it. Removes a lot of html tags that could cause problems, strips slashes if necessary.
$this->ipsclass->clean_evil_tags( string val )
Removes tags that would (most commonly) be used for cross site scripting attacks through javascript (or that could potentially break the display of the page if rendered).
$this->ipsclass->remove_tags( string val )
Removes the tags used by the global board wrapper so that they won't get replaced through input data instead of the templates when the templating engine is called.
$this->ipsclass->is_number( int val )
Verifies if the input is a number or not (returns the number if it is, else returns nothing).
$this->ipsclass->set_up_guest()
Returns an array of default member data for a guest.
$this->ipsclass->get_avatar( string var, [int val, [string val, [string val]]] )
Returns an avatar image. You must pass the first parameter, which is the member's avatar stored value. The second parameter is a setting on whether the member is viewing avatars, the third value is the dimensions if specified, and the final parameter is the type (url, local or upload).
$this->ipsclass->quick_init()
Quick initialization to perform tasks that don't need all the cache/templates/etc loaded.
$this->ipsclass->Error( array )
Produces the IPB error screen. Pass it LEVEL, and MSG and that should be enough. There are two other params, but they are unimportant for modders as of yet. MSG is the language bit key to use (if you have loaded your own custom language file, this can be used. Else you can use a key in lang_errors by default).
$this->ipsclass->board_offline()
Shows board offline message when appropriate.
$this->ipsclass->select_var( array )
Designed so you can pass this function an array of selectable variable options. It will return the chosen variable (the selected one). Likely never a time you would find a use for this function.
$this->ipsclass->array_filter_clean_read_topics( string var )
Determines if the value passed to this function is greater than the cut off date for storing read topics.
$this->ipsclass->load_words( array, string var, string var )
Deprecated: you pass this function your current language bit array as argument 1, then pass it the filename in argument 2 and the language folder in argument 3 and it loads the language bits and returns the merged array. You should use load_language instead.
This is the general contents of $this->ipsclass. As you will notice there is a lot of information and lot of methods you can utilize. Don't forget DB and print are objects under ipsclass as well. We'll leave those for another discussion however. ;) Comments welcome. :)
[/quote]
In 2.1, most of the same properties and methods are still available, however you will access them through $this->ipsclass instead (in 99% of the instances in which you will need to know this).
$ipsclass is instantiated in index.php, and a reference to it is passed to each object that is created. Let's take a look at some of the properties and methods available, as well as the objects you can access through $ipsclass.
$this->ipsclass->DB->function_name()
The old $DB has been moved to $this->ipsclass->DB. Just about all of the functions have retained the same name as was used in 2.0, so you should mostly be able to just update $DB to $this->ipsclass->DB in your files and be good to go. Just remember you don't have to globalize anything now since you have the pseudo-variable $this to use.
$this->ipsclass->print->function_name()
The old $print has been moved to $this->ipsclass->print. Most of the calls are the same, so you have little changes to make here as well.
$this->ipsclass->ip_address
Contains the IP address of the current viewer. Uses the settings in the ACP regarding the matching of X_FORWARDED_FOR IP addresses.
$this->ipsclass->vars['variable_name']
All those variables that are added to the system cache (mostly the default settings available upon installation of the board, but modifications can be set to be added to the system cache as well) will be stored in this array. Replace 'variable_name' with the key you used to add the setting. You can take a look at the settings available in this array by going into the ACP->Tools & Settings->Cache Control and hit the button next to settings, and hit View Cache. You'll get a popup window with the array printed out.
$this->ipsclass->cache['cache_store_key']
You can add entries to the forums_cache_store table, and then load them up when your page is called (either through your file under sources/components_init/, or by adding the key to the $choice array in index.php). The cache_store_key will be the cs_key in forums_cache_store. If you set the record in the database to be an array (cs_array=1), then the array will be unserialized and stored here. Thus, you can access it through $this->ipsclass->cache['cs_key']['value_in_array'].
$this->ipsclass->member['array_value']
This is the data for the current member.
Note: You should be using 'members_display_name' from this array to get the current user's name, rather than the 'name' value. This is the case as of 2.1.0.
Note that not EVERY column from forums_members is stored here. Also note that nearly all columns from forums_groups are stored in this array, and an additional 'is_mod' key is set to a 1 or a 0, depending upon whether the member is a moderator or not.
$this->ipsclass->input['form_or_url_value']
This array holds all GET and POST keys (merged, POST overwrites GET) already cleaned and ready for use. As a modification author, it is still always your responsibility to code with security in mind, however common "baddies" are removed from these keys and values (such as ' " < and > characters).
$this->ipsclass->time_options
$this->ipsclass->num_format
$this->ipsclass->get_magic_quotes
$this->ipsclass->query_string_safe
$this->ipsclass->query_string_real
$this->ipsclass->user_agent
$this->ipsclass->browser
$this->ipsclass->operating_system
$this->ipsclass->can_use_fancy_js
Stores some properties for the script to access. Time options is used when calling get_date(), as is num_format. get_magic_quotes stores the current setting of get_magic_quotes_gpc(). Query string safe is a "safe" formatted query string with & entities, while query_string_real contains the actual query string with &.
The user agent, browser and OS are stored in the next three properties.
can_use_fancy_js is determined if the user has a compatible version of Mozilla or IE that will allow the AJAX-type and RTE javascript functions to work. Support for other browsers will likely be added as they adopt the specifications.
$this->ipsclass->init_load_cache( [array] )
You pass an array of cs_key values. The function loads them into $this->ipsclass->cache['cs_keys'] (cs_keys being the keys you pass to the function). You should attempt to load your cache when this function is first called (using the components_init/ plugin style, or by specifying the keys to load in index.php if you add a new "act=" page, as each call to this function will result in an additional (unnecessary) database query.
$this->ipsclass->init_db_connection()
Initilizes database connection based on the configuration settings currently set. There should be very few times you need to call this manually, as it has already been done for you in index.php.
$this->ipsclass->fetch_os()
Again, few times you should need to use this, as this function is called automatically and the result is stored in $this->ipsclass->operating_system. Return values include "mac", "windows", and "unknown".
$this->ipsclass->fetch_browser()
Another function you should not have to spend much time learning. The value is already stored in $this->ipsclass->browser as an array. Keys are 'browser' and 'version'.
$this->ipsclass->load_class( string var, string var, [string var] )
This function, while useful, is commonly not used. This function loads a class. First argument is the file name (including path information). The second argument is the class name. If you have a constructor function in the class (PHP 5, ___construct(), or PHP 4, function with same name as class name) that accepts an argument, you can pass it the argument through this function as well. The third argument this function accepts is an optional argument you wish to pass to the class you are loading.
$this->ipsclass->can_queue_posts( [string var] )
This function determines if this user can manager queued posts. The optional argument is a forum id (if you wish to check a specific forum).
$this->ipsclass->get_multimod( string var )
Checks if a user can use the multi-mod tool, and if so returns an array of allowed actions (based on their privileges set in the ACP). The argument is required, and is the forum id to check against.
$this->ipsclass->unpack_member_cache( array )
While not exactly *required*, if the serialized array is not passed to this function it will serve no purpose. This function is designed to take a serialized array and return it unserialized.
$this->ipsclass->pack_and_update_member_cache( int var, array, [array] )
This function stores the members cache (in forums_members.members_cache). The int you pass to it is the member id (probably most often $this->ipsclass->member['id']). The first array (required) is the array you would like to store in this members members_cache record. The last (optional) array is the existing cache record. This is required, however if you do not pass this array to the function, it will load the member's existing cache record for you.
The two arrays are merged and the resulting array is serialized and stored back in the members table.
Really there should be just about no times when you need to use this function.
$this->ipsclass->update_forum_cache()
Updates the forum cache, just as indicated. Unlike the other caches, you do not need to populate $this->ipsclass->cache['forum_cache'], as this function will do it for you when it is called.
$this->ipsclass->update_cache( array )
Updates the record in the forums_cache_store table. The array accepts 'name', 'value', 'array', 'deletefirst', and 'donow'. deletefirst and donow are flags to tell the function whether to first delete the record, and then store a new one (versus updating an existing record), and the donow flag indicates if the cache should be updated when this function is called, or just flagged to be updated on shutdown.
The name is the cs_key. The array key is a flag to indicate if the value is an array or not. Arrays are serialized before they are stored (and automatically unserliazed with the init_load_cache function). The value is the value to be stored. You can optionally NOT pass the value, and store it in $this->ipsclass->cache[ 'name' ] (where name is the name you pass to the function). This function will automatically use that value if none is passed.
Common usage is to store statistics or something similar that you don't want to have to generate on the fly on each page load. When it is time to update the value, you update the value in $this->ipsclass->cache['keyname']['value'] and the entire array (or single value) is available in your script immediately, plus the update_cache function will have access to it as well. Either way works.
$this->ipsclass->my_deconstructor()
deconstructor function. Runs miscellaneous stored database queries, closes database connection, and sends any pending emails stored through the process_mail_que function).
$this->ipsclass->process_mail_queue()
Sends queued emails in increments. This function is called on each page load (on shutdown) processing remaining emails.
$this->ipsclass->acp_load_template( string var )
Loads a template file to be used in the ACP (file should be located under skin_acp/IPB2_Standard/acp_skin_html). You can first set $this->ipsclass->skin_acp to be a different directory and IPB2_Standard will be replaced with the directory you specified.
$this->ipsclass->acp_load_language( string var )
Loads a language file to be used in the ACP. Language abstraction for the ACP is expected in 3.0, however this has not been finalized.
$this->ipsclass->load_template( string var, [int var] )
Loads a skin template. Loads all functions in the skin template into $this->ipsclass['compiled_templates'][ $name ]->template_function_name( args ). Note: $name is the name you pass in the first argument to this function, and template_function_name( args ) are the functions in this template. Args is optional, depending upon what your skin template requires.
The second parameter is an id, and will force the function to load the skin id specified rather than (necessarily) the current skin set id for the browsing user. Some other properties are set at this time (such as $this->ipsclass->loaded_templates and $this->ipsclass->skin['_type']).
$this->ipsclass->load_skin()
Loads a skin set. Accepts no arguments, loads the skin set based on the members skin choice or the board default (or a forum-specific skin, when applicable). Set's the $this->ipsclass['_skin'] properties.
$this->ipsclass->load_language( string var )
Loads a language file based on the user's default language set (or the board's default language set, if the user has not specified a language set, or only one is available). The required argument is the language file name (without .php at the end).
$this->ipsclass->get_new_pm_notification( [int var, [int var]] )
The first optional parameter is the limit (how many you would like to pull). The second is a flag to specify if this is an XML AJAX request or a standard request. This returns the fully formatted new pm notification box html and is claled (by default) from class_display.php
$this->ipsclass->txt_convert_charsets( string var, string var, [string var] )
This function converts between character sets. Quite nifty. The first argument is the text to convert. The second argument is the character set we are converting FROM. The third argument is the character set to convert to. If this is not passed, the default character set specified in the ACP is used.
This function will try to first use the php function 'mb_convert_encoding', then 'recode_string', followed by 'iconv'. If it is unable to use any of those functions it simply returns the text you passed it. This means you are responsible for ensuring the text is actually converted.
$this->ipsclass->txt_truncate( string var, [int var] )
Truncates a string without breaking html entities. The first argument is the string (likely html formatted), the second argument is the position to truncate to. Default is 30 characters.
$this->ipsclass->txt_alphanumerical_clean( string var )
Returns an alphanumeric only string.
$this->ipsclass->txt_mb_strlen( string var )
Returns the size/length of a multi-byte string.
$this->ipsclass->txt_stripslashes( string var )
Takes into account $this->ipsclass->get_magic_quotes and determines how to properly strip the slashes off of the string. Returns a string with extra slashes stripped.
$this->ipsclass->txt_raw2form( string var )
Takes a string and formats it so it is safe to use in a textarea.
$this->ipsclass->txt_form2raw( string var)
Unconverts text for use in a textarea (specifically, the $ and \ characters).
$this->ipsclass->txt_safeslashes( string var )
Attempt to safely slash the data for input into a database.
$this->ipsclass->txt_htmlspecialchars( string var )
Convert some of the common html entities, includes multi-byte character support.
$this->ipsclass->txt_UNhtmlspecialchars( string var )
Opposite of last function, unconverts the entities the txt_htmlspecialchars converted, includes multi-byte character support.
$this->ipsclass->txt_windowstounix( string var )
Converts Windows (\r\n) (and Mac (\r) ) newlines to Unix newlines.
$this->ipsclass->return_md5_check()
Creates an md5 hash that can be used to validate form input and such. The md5 hash is generated based on some static factors so that an identical hash can be created later and compared to the first hash. Common usage is to add this hash into a form, and then check it when the form is submitted.
$this->ipsclass->trim_leading_comma( string var )
Trims the leading comma of a string.
$this->ipsclass->trim_trailing_comma( string var )
Trims the trailing comma of a string.
$this->ipsclass->clean_comma( string var )
Removes duplicate commas (more than one in a sequence). Useful if you are imploding an array into a comma separated string and the possibility of blank array values existed.
$this->ipsclass->clean_perm_string( string var )
This is a wrapper for the other 3 comma functions. Calls the other three functions for you (so you can make one function call instead of 3 separate ones in your script).
$this->ipsclass->math_strlen_to_bytes( int val )
Converts strlen value to bytes.
$this->ipsclass->size_format( int val )
Converts a size (in bytes) to a human readable size with KB or MB at the end (or bytes, if it is less than 1 kb).
$this->ipsclass->print_forum_rules( int val )
When passed the one (required) argument, this function prints the forum rules for the forum id passed. The returned value is fully formatted based on the html template used.
$this->ipsclass->hdl_ban_line( array )
Pass this function an array with unit, and timespan set, or pass this function a time in format date_start:date_end:timespan:unit and a ban timeframe is returned.
$this->ipsclass->check_perms( array )
You must first set $this->ipsclass->perm_id_array with your permission array. Then you pass the user's set permission array, and a TRUE/FALSE comparison is done to determine if the user is permitted or not. Your script would be responsible for stopping the user if FALSE is returned.
$this->ipsclass->create_perms_from_group( string var )
This function accepts a comma separated string of group ids, and then returns a comma separated string of permission mask ids associated with those groups.
$this->ipsclass->do_number_format( int val )
Formats a number based on settings specified in the ACP for number formatting.
$this->ipsclass->hdl_forum_read_cookie( [string val])
Sets/gets a cookie specifying the forums this user has read.
$this->ipsclass->scale_image( array )
Array should contain 'max_width', 'max_height', 'cur_width', and 'cur_height. The function returns an array with 'img_height' and 'img_width' set. The values should proportionately resize the image so that it falls within the maximum settings you sent.
$this->ipsclass->show_gif_img( int val )
Generates and displays a random number as an image for the anti-spam controls.
$this->ipsclass->show_gd_img( int val )
Same as above, only using GD (which is harder for bots/scripts to analyze and return the actual values from).
$this->ipsclass->my_nl2br( string var )
Passed a string, this function will turn new lines into XHTML br tags.
$this->ipsclass->my_br2nl( string var )
Does the opposite of the last function, turning br tags into newlines.
$this->ipsclass->make_profile_link( string var, [int val] )
You pass this function a name and an id, and it returns a profile link (based on the input values). This function does not verify if the data is accurate. It only verifies the id is > 0 and returns a link if it is, else just the name.
$this->ipsclass->boink_it( string val )
The input string should be a (valid) url. This function will use your setting in the ACP to determine the type of redirect to utilize. Location headers (or Refresh headers on Windows) are optimal, however this function supports a "meta redirect" in case some of your php files are outputting white space causing the headers not to work.
$this->ipsclass->make_password()
Returns a random 8 character password.
$this->ipsclass->folder_icon( array, [int val], [int val] )
This function is designed to determine the appopriate topic folder icon. You pass this function the topic information in the array, set the second argument to 1/0 depending upon if you were the topic starter, and optionally send the time you wish to compare against (last_visit time is used if this is ommitted), and this function determines which icon is appropriate to display.
$this->ipsclass->text_tidy( string val )
Takes raw text from a database and converts to all html entities. Uses the html entity translation, as well as some regular expression matching to try to convert everything for a textarea (or for storage, theoretically). This function does not check if characters have already been html converted, thus it would turn & into &amp;. Use this function at your own risk.
$this->ipsclass->build_pagelinks( array )
One of my favorite functions, this is a simple, yet powerful one. It builds page links, that's it. But it saves you the trouble of having to determine how many records were on each page, and where did you start at, and how many are left and so forth.
You pass this function an array with the following keys set appropriate:
leave_out (number of pages to show to each side of current page before adding the ...)
USE_ST (whether to set the page start number at st= or something customized...this is the record your user is starting at, typically used in your querie's limit cause to produce LIMIT {perpage},{st})
TOTAL_POSS (the number of total records)
PER_PAGE (how many records per page)
CUR_ST_VAL (current value of st=, or your custom start value point)
BASE_URL (the base url to append to...this should be a full url, containing any search or other parameters...num and st will be appended to indicate the current record you are at, and how many per page you are viewing)
L_SINGLE (the string to display if only a single page is recorded)
$this->ipsclass->build_forum_jump( int val, [int val, [int val]])
Builds the forum jump list, taking into account whether you set the option enable short forum jump list in the acp or not. The first argument specifies whether the full html should be returned or not (you may not want all the html if you are making your own drop down, or making a multi-select). The second flag overrides the short forum jump list setting, and the third flag removes redirect forums from the list.
$this->ipsclass->clean_email( string val )
Verifies an email address and returns TRUE or FALSE depending upon whether it appears to be valid.
$this->ipsclass->get_date( string val, string val, [int val, [int val]] )
This function will accept a timestamp in the first argument, and a method (in the valid list of methods found under the property time_options discussed above), and format it into a readable date based on the method requested. The third argument forces removal of relative dates (today, yesterday), and the fourth argument is to specify if you do wish to use relative dates. It is override within the function, so there is no point passing it. Takes into account your date settings in the ACP, as well as the members and boards time zone offsets.
$this->ipsclass->get_time( string val, string val )
This is similar to get date except that the second argument is a date() compliant method of formatting a timestamp into a date. The first argument is still the timestamp. Time zone settings are *not* taken into account.
$this->ipsclass->get_time_offset()
Returns the current users applied time zone offset in minutes (which will be the board time zone offset if none is specified).
$this->ipsclass->convert_local_date_to_unix( array )
Pass in an array with hour, minute, month, day, year specified and a timestamp is returned (minus the offset that is returned automatically from get_time_offset()).
$this->ipsclass->unixstamp_to_human( string val )
Accepts a timestamp and returns an array with minute, hour, day, month, and year set appropriately.
$this->ipsclass->date_gmmktime( int val, int val, int val, int val, int val, int val )
Nearly identical to gmmktime().
$this->ipsclass->date_getgmdate( string val )
Nearly identical to getdate().
$this->ipsclass->my_setcookie( string val, string val, [int val] )
Sets a cookie (first argument) with value (second argument) based on cookie settings in ACP. The third optional parameter specifies if it should be a stickie cookie (not expire anytime in the near future).
$this->ipsclass->my_getcookie( string val )
Returns the cookie specified by the input name. If you use my_setcookie, then on another page load you can use my_getcookie to obtain the value originally set.
$this->ipsclass->parse_incoming()
Called automatically, this populates $this->ipsclass->input (and calls the functions to clean the keys and values for you).
$this->ipsclass->parse_clean_key( string val )
Takes the string value input and cleans it for usage as an array key.
$this->ipsclass->parse_clean_value( string val )
Parses the value sent to this function and cleans it. Removes a lot of html tags that could cause problems, strips slashes if necessary.
$this->ipsclass->clean_evil_tags( string val )
Removes tags that would (most commonly) be used for cross site scripting attacks through javascript (or that could potentially break the display of the page if rendered).
$this->ipsclass->remove_tags( string val )
Removes the tags used by the global board wrapper so that they won't get replaced through input data instead of the templates when the templating engine is called.
$this->ipsclass->is_number( int val )
Verifies if the input is a number or not (returns the number if it is, else returns nothing).
$this->ipsclass->set_up_guest()
Returns an array of default member data for a guest.
$this->ipsclass->get_avatar( string var, [int val, [string val, [string val]]] )
Returns an avatar image. You must pass the first parameter, which is the member's avatar stored value. The second parameter is a setting on whether the member is viewing avatars, the third value is the dimensions if specified, and the final parameter is the type (url, local or upload).
$this->ipsclass->quick_init()
Quick initialization to perform tasks that don't need all the cache/templates/etc loaded.
$this->ipsclass->Error( array )
Produces the IPB error screen. Pass it LEVEL, and MSG and that should be enough. There are two other params, but they are unimportant for modders as of yet. MSG is the language bit key to use (if you have loaded your own custom language file, this can be used. Else you can use a key in lang_errors by default).
$this->ipsclass->board_offline()
Shows board offline message when appropriate.
$this->ipsclass->select_var( array )
Designed so you can pass this function an array of selectable variable options. It will return the chosen variable (the selected one). Likely never a time you would find a use for this function.
$this->ipsclass->array_filter_clean_read_topics( string var )
Determines if the value passed to this function is greater than the cut off date for storing read topics.
$this->ipsclass->load_words( array, string var, string var )
Deprecated: you pass this function your current language bit array as argument 1, then pass it the filename in argument 2 and the language folder in argument 3 and it loads the language bits and returns the merged array. You should use load_language instead.
This is the general contents of $this->ipsclass. As you will notice there is a lot of information and lot of methods you can utilize. Don't forget DB and print are objects under ipsclass as well. We'll leave those for another discussion however. ;) Comments welcome. :)
[/quote]