Retired Documentation: You are using the documentation for version 1.7.3 which was retired in 2013. Go here for the latest version documentation or check here for your available upgrades to the latest version.

Functions Class

The Functions class contains commonly required functions used throughout ExpressionEngine's scripts.

set_realpath(path [string])

Returns realpath for a directory or file.

Class: Functions (FNS)

Description: Takes a path and attempts to determine the full server path for it.

fetch_site_index(add_slash [int], session_id [int])

Returns site's main index URL.

Class: Functions (FNS)

Description: Returns the url of the main site index. If add_slash is set to 1, then a slash is added to the end of the string. If session_id is set to 1, then the session id is included (if sessions are being used on the user side and this function is called in a 'webpage' template). Alternatively, those two values can be set to 0 and no slash will be added and no session id will be added, respecively. Default is 0 for add_slash and 1 for session_id.

create_url(segment [string], trailing_slash [boolean], session_id [int])

Returns url for site.

Class: Functions (FNS)

Description: The segment inputed to this function is parsed and added to the full site URL to create a full URL/URI. If trailing_slash is set to true, then a slash is added to the end of the string. If session_id is set to 1, then the session id is included (if sessions are being used on the user side). Alternatively, trailing_slash and session_id can be set to false/0 and no slash will be added and no session id will be added, respecively. Default is true for add_slash and 1 for session_id.

$memberlist_url = $FNS->create_url('member/memberlist');

// returns "http://example.com/index.php/member/memberlist/"

fetch_current_uri()

Returns uri for current page.

Class: Functions (FNS)

Description: Returns the full URI for the current page. Occassionally, used in forms when a return location is not set by default.

remove_double_slashes(str [string])

Remove duplicate slashes from URL.

Class: Functions (FNS)

Description: A clean up function that removes all double slashes (//) from str and returns the string. Useful for cleaning up URLs. The double slashes in http:// are preserved.

remove_session_id(str [string])

Removed session IDs from a URL.

Class: Functions (FNS)

Description: A clean up function that removes the session ID from str, which should be a URL, and returns the string. An example of usage is if you are sending email notifications for a form upon submit (i.e. comments) and including the form's URL in the email being sent.

extract_path(str [string])

Removed session IDs from a URL.

Class: Functions (FNS)

Description: Extract the template group/template name from str, like {some_var path="weblog/index"}, and returns just the path.

// Parse permalink path
$key = '{permalink path="weblog/details"}'
if ($FNS->extract_path($key) != '' && $FNS->extract_path($key) != 'SITE_INDEX')
{
	$path = $FNS->extract_path($key).'/'.$row['entry_id'];
}
// function returns 'weblog/details'

var_swap(str [string], data [array])

Replace array of variables in string.

Class: Functions (FNS)

Description: Returns a string where the data array is used to replace all of the occurrences of the data's keys with data's values in str.

$str = "Rick and Paul ate {meal} while sitting around the {item}"; 

$swap = array('meal' => "Skittles", 'item' => "computer");

$msg = $FNS->var_swap($str, $swap);

// returns "Rick and Paul ate Skittles while sitting around the computer";

redirect(location [string])

Redirect to location.

Class: Functions (FNS)

Description: Redirects current browser page to location. Does redirect either by location or meta refresh, depending on the redirect method preference.

hash(str [string])

Convert a string into a SHA1 encrypted hash.

Class: Functions (FNS)

Description: Returns str as a SHA1 encrypted hash.

random(type [string], length (string int))

Random number/password generator.

Class: Functions (FNS)

Description: Returns a random string based on the type and length specified. The default type is 'encrypt'.

There are four possible values for type:

basic - just a random number
alpha - string with length of length using only letters (upper and lower case) of the alphabet
numeric - string with length of length using only numbers
nozero - string with length of length using all numbers except zero
md5 - string of a random number that has been md5'ed
encrypt - string of a random number that has been hash'ed

form_declaration(data [array])

Creates opening form tag and hidden variables.

Class: Functions (FNS)

Description: The data array contains the attributes and any hidden fields for the form tag.

$form_details = array('action'	   => '',
				  'name'	   => 'upload',
				  'id'		   => 'upload',
				  'hidden_fields'  => array('new' => 'y'),
				  'secure'	   => TRUE,
				  'onsubmit' => "validate_form(); return false;"
				  );

$r = $FNS->form_declaration($form_details);

form_backtrack(offset [int])

Returns a URL for previosly viewed page.

Class: Functions (FNS)

Description: Returns a URL that allows us to return a user to a previously visited page after submitting a form. ExpressionEngine keeps track of the last five pages viewed by a visitor, and the page returned is determined by the value of offset. For example, 0 is the current page, -1 would be the form page, and -2 would be the page prior to the form page.

$data = array('title'   => 'Information Accepted',
			  'heading'	=> 'Thank you',
			  'content'	=> 'Thank you for the locale information',
			  'link'    => array($FNS->form_backtrack('-2'), 'Return to entry')
			  );

$OUT->show_message($data);

evaluate(str [string])

Evaluates a string as PHP

Class: Functions (FNS)

Description: Evaluates a str as PHP

$str = "echo 3*4;";

ob_start();

echo $FNS->evaluate($str);
$value = ob_get_contents();

ob_end_clean();

// $value is now equal to 12, since that is what would be outputted by the PHP.

set_cookie(name [string], value [string], expire [int])

Sets cookie for site.

Class: Functions (FNS)

Description: Sets cookie based on name and value. The optional expire parameter is added to the current time to specify when the cookie expires. If not set or set to '', then the cookie expiration is set in the past and should usually be evaluated as having expired.

The advantage to using this function over just the standard PHP function is because EE will automatically add the cookie domain, cookie prefix, and cookie path as specified in the preferences. Those are helpful for making these cookies unique to EE and not interfering with other cookies set for your site by other software.

char_limiter(str [string], num [int])

Returns section of a string based on number of character.

Class: Functions (FNS)

Description: When given a str, it will return the string limited to a certain amount of characters but rounds the string up to the nearest word. The num parameter is optional and by default is set to 500 characters

word_limiter(str [string], num [int])

Returns section of a string based on number of words.

Class: Functions (FNS)

Description: When given a str, it will return the number of words specified by num. The num parameter is optional and by default is 100.

fetch_email_template(name [string])

Returns the contents of email template.

Class: Functions (FNS)

Description: Returns the contents of the email template requested based on the language settings of the user.

encoding_menu(which [str], name [str], selected [str])

Returns character encoding or language form select menu

Class: Functions (FNS)

Description: The which variable can be set to either 'languages' or 'charsets', and the name must be set to whatever you want the form field to be named. The optional value selected is for indicating the selected value or the default value for the pulldown.

echo $FNS->encoding_menu('languages', 'xml_lang', 'ab');
//  Displays:
//  <select name="xml_lang">
//  <option value='aa'>Afar</option>
//  <option value='ab' selected='selected'>Abkhazian</option>
//  <option value='af'>Afrikaans</option>
//  etc...
//  </select>

create_directory_map(directory [str], top_level_only [bool])

Returns array of files and folders in a directory

Class: Functions (FNS)

Description: Specify a directory and this function will create an array mapping out all the files and folders in that directory, including any sub-folder files. This functions uses multi-level arrays to show sub-folder depth.

language_pack_names(default [str])

Returns form select menu of avaialable language packs

Class: Functions (FNS)

Description: The optional parameter default is used to specify the currently selected or default value.

clear_caching(which [str], sub-directory [str], relationships [bool])

Clears one or all of the main cache folders

Class: Functions (FNS)

Description: Set which to one of the six values 'page', 'tag', 'db', 'sql', 'relationships', 'all' to empty the main ExpressionEngine cache directories. The optional parameter sub_directory can be used to specify a specific folder or file in that the directories. relationships used only when clearing 'all' caches, lets you specify whether or not relationship caches should be emptied as well. Default is FALSE.

There are certain times when changing data (prefs or templates, for instances) when you want changes to appear immediately. This allows you to clear the cache files and make sure the changes appear on the next viewing of the site.

delete_directory(path [str], delete root [boolean])

Empties a directory of any files.

Class: Functions (FNS)

Description: Set path to the absolute path of the directory you wish to empty. Remember to use the EE defined PATH constants to assist you in creating these paths.

If you wish to delete the folder as well as the contents inside of it, then set the optional parameter delete root to TRUE, by default it is set to FALSE.

fetch_assigned_weblogs()

Returns array of weblogs accessible by current user.

Class: Functions (FNS)

Description: Returns array of weblogs accessible by current user.

fetch_action_id(class [str], method [str])

Returns action id of action in the database

Class: Functions (FNS)

Description: Modules have certain actions for forms, links, etc. that are recognized via an action ids that are inserted into the database upon installation of that module.

$action_id = $FNS->fetch_action_id('Comment', 'insert_new_comment');

create_captcha()

Returns <img> tag for newly created captcha

Class: Functions (FNS)

Description: Using a random word chosen from the array stored in the words.php file, this function will create a captcha image and then store that word and the IP address of the current user in the database. You can then put the returned <img> tag in your form along with a text input field for the user submitted word. When the form is submitted you can check the submitted word against the database for the user's IP. If it matches, you continue processing the form data. If it does not, then the form should fail. This is used to prevent automated spamming tools from submitting spam.

sql_andor_string(str [str], field [str], prefix [str])

Returns query string when tag parameter usings pipes

Class: Functions (FNS)

Description: Certain tag parameters have the option to be in the form of 'value1|value2' or 'not value1|value2', which allows the acceptance of multiple values. This function takes that parameter as str and the field to check, along with the (optional) prefix of the table containing the field, and returns the query string required.

$str  = 'weblog|news|sports';
$sql  = "SELECT * FROM exp_weblogs WHERE is_user_blog = 'n' ";
$sql .= $FNS->sql_andor_string($str, 'blog_name');
// $sql equals:
// SELECT * FROM exp_weblogs WHERE is_user_blog = 'n'
// AND blog_name = 'weblog' OR blog_name = 'news' OR blog_name = 'sports'

assign_variables(str [string], slash [string])

Assign variables of tag to array

Class: Functions (FNS)

Description: This function extracts the variables contained within the current tag being parsed and assigns them to one of two arrays which are returned to you: var_single or var_pair. The slash variable is used to determine what form the backslash in tags is in, character (/) or entity (/).

fetch_date_variables(str [string])

Fetch date variables from tag

Class: Functions (FNS)

Description: This function looks for a variable that has this prototype: {date format="%Y %m %d"}. If found, returns only the datecodes: %Y %m %d.

assign_parameters(tag [string])

Fetch parameters for tag

Class: Functions (FNS)

Description: Returns an array of parameters for the tag.

prep_conditionals(str [string], variables [array], safety [string], prefix [string])

Parses conditionals and preps conditional for evaluation

Class: Functions (FNS)

Description: The first two parameters are requried. If safety is set to 'y', then some safety checks are performed to make sure conditionals are well formed. Normally, do not set this parameter. The prefix is used when your variables might have a prefix (ex: (your_prefix->var_name}), so that you only have to send the normal variables and the prefix opposed to two sets of variables (one with prefix and one without).

filename_security(filename [string])

Cleans a filename

Class: Functions (FNS)

Description: Takes the filename and cleans it of any unwanted characters or strings for security.