Retired Documentation
You are using the documentation for version 2.11.9. Go here for the latest version or check here for your available upgrades to the latest version.
Functions Class¶
-
class
Functions
¶ The Functions class contains commonly required functions used throughout ExpressionEngine’s scripts.
- fetch_site_index
- create_url
- fetch_current_uri
- remove_double_slashes
- extract_path
- var_swap
- redirect
- random
- form_declaration
- form_backtrack
- evaluate
- char_limiter
- word_limiter
- fetch_email_template
- language_pack_names
- clear_caching
- delete_directory
- fetch_assigned_channels
- fetch_action_id
- create_captcha
- sql_andor_string
- assign_variables
- fetch_date_variables
- assign_parameters
- prep_conditionals
fetch_site_index¶
-
Functions::
fetch_site_index
([$add_slash = FALSE[, $sess_id = TRUE]])¶ Returns the url of the main site index.
Parameters: - $add_slash (boolean) – Set to
TRUE
to add a slash to the end of the return value - $sess_id (boolean) – Set to
FALSE
to exclude the session id
Returns: Site index URL
Return type: String
- $add_slash (boolean) – Set to
create_url¶
-
Functions::
create_url
($segment[, $sess_id = TRUE])¶ The segment passed to this function is parsed and added to the full site URL to create a full URL/URI.
$memberlist_url = ee()->functions->create_url('member/memberlist'); // returns "http://example.com/index.php/member/memberlist/"
Parameters: - $segment (string) – The desired URL’s URI
- $sess_id (boolean) – If set to
FALSE
, session_id will not be included
Returns: Full site URL pointing to
$segment
Return type: String
fetch_current_uri¶
-
Functions::
fetch_current_uri
()¶ Returns uri for current page.
Returns: Current URI Return type: String
remove_double_slashes¶
-
Functions::
remove_double_slashes
($str)¶ Deprecated since version 2.6: Use String helper’s
reduce_double_slashes()
instead.Removes all double slashes (
//
) from$str
and returns the string. Useful for cleaning up URLs. The double slashes inhttp://
are preserved.Parameters: - $str (string) – String to remove double slashes from
Returns: Cleaned up
$str
Return type: String
extract_path¶
-
Functions::
extract_path
($str)¶ Extract the template group/template name from
$str
, like{some_var path='channel/index'}
, and returns just the path.// Parse permalink path $key = '{permalink path='channel/details'}' if (ee()->functions->extract_path($key) != '' && ee()->functions->extract_path($key) != 'SITE_INDEX') { $path = ee()->functions->extract_path($key).'/'.$row['entry_id']; } // function returns 'channel/details'
Parameters: - $str (string) – String to extract the path from
Returns: Template group/name pair
Return type: String
var_swap¶
-
Functions::
var_swap
($str, $data)¶ Replace array of variables in string:
$str = "Rick and Paul ate {meal} while sitting around the {item}"; $swap = array('meal' => "Skittles", 'item' => "computer"); $msg = ee()->functions->var_swap($str, $swap); // returns "Rick and Paul ate Skittles while sitting around the computer";
Parameters: - $str (string) – String to parse
- $data (array) – Associative array of keys to replace with values
Returns: $str
parsed with$data
Return type: String
redirect¶
-
Functions::
redirect
($location[, $method = FALSE[, $status_code = NULL]])¶ Redirect to location.
Parameters: - $location (string) – URL to redirect to
- $method (string) – Optionally choose a method to redirect with
(can use
refresh
, otherwise defaults to usingLocation
header) - $status_code (integer) – Status code in the 300 block
Return type: Void
random¶
-
Functions::
random
([$type = 'encrypt'[, $len = 8]])¶ Random number/password generator.
Parameters: - $type (string) –
There are four possible values:
basic
- just a random numberalpha
- string with length of length using only letters (upper and lower case) of the alphabetnumeric
- string with length of length using only numbersnozero
- string with length of length using all numbers except zeromd5
- string of a random number that has beenmd5
’edencrypt
- string of a random number that has been hash’ed
- $len (integer) – Length of the string
Returns: Random string of characters
Return type: String
- $type (string) –
form_declaration¶
-
Functions::
form_declaration
($data)¶ Creates opening form tag and hidden variables.
Any form will accept the
form_class
andform_id
parameters. Access the values with TMPL class properties ofform_id
andform_class
.$form_details = array( 'action' => '', 'name' => 'upload', 'id' => ee()->TMPL->form_id, 'class' => ee()->TMPL->form_class, 'hidden_fields' => array('new' => 'y'), 'secure' => TRUE, 'onsubmit' => "validate_form(); return false;" ); $r = ee()->functions->form_declaration($form_details);
Parameters: - $data (array) – Associative array of data (see above for example)
Returns: Opening form tag and hidden fields
Return type: String
form_backtrack¶
-
Functions::
form_backtrack
([$offset = ''])¶ 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.
$data = array( 'title' => 'Information Accepted', 'heading' => 'Thank you', 'content' => 'Thank you for the locale information', 'link' => array(ee()->functions->form_backtrack('-2'), 'Return to entry') ); ee()->output->show_message($data);
Parameters: - $offset (integer) – How many pages you want to backtrack:
0
is the current page,-1
would be the form page, and-2
would be the page prior to the form page.
Returns: Previous URL
Return type: String
- $offset (integer) – How many pages you want to backtrack:
evaluate¶
-
Functions::
evaluate
($str)¶ Evaluates a string as PHP:
$str = "echo 3*4;"; ob_start(); echo ee()->functions->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.
Parameters: - $str (string) – String to evaluate as PHP
Returns: Resulting value
Return type: String
char_limiter¶
-
Functions::
char_limiter
($str[, $num = 500])¶ Returns section of a string limited to a certain amount of characters but rounds the string up to the nearest word.
Parameters: - $str (string) – String to limit
- $num (interger) – Characters to limit to
Returns: Limited string
Return type: String
word_limiter¶
-
Functions::
word_limiter
($str[, $num = 100])¶ Returns section of a string based on number of words.
Parameters: - $str (string) – String to limit
- $num (interger) – Words to limit to
Returns: Limited string
Return type: String
fetch_email_template¶
-
Functions::
fetch_email_template
($name)¶ Returns the contents of the email template requested based on the language settings of the user.
Parameters: - $name (string) – Name of the email template
Returns: Email template parsed with the user’s language
Return type: String
language_pack_names¶
-
Functions::
language_pack_names
($default)¶ Returns form select menu of available language packs
Parameters: - $default (string) – Currently selected or default language
Returns: Div tag with a select tag that contains the listing of languages
Return type: String
clear_caching¶
-
Functions::
clear_caching
($which[, $sub_dir = ''])¶ Clears one or all of the main cache folders
Parameters: - $which (string) –
'page'
,'tag'
,'db'
,'sql'
,'relationships'
,'all'
- $sub_dir (string) – Define a specific folder or file in the cache directory
Return type: Void
- $which (string) –
delete_directory¶
-
Functions::
delete_directory
($path[, $del_root = FALSE])¶ Empties a directory of any files.
Parameters: - $path (string) – Absolute path of the directory you wish to empty; remember to use the path constants to make this easier
- $del_root (boolean) – Set to
TRUE
to delete the directory as well
Return type: Void
fetch_assigned_channels¶
-
Functions::
fetch_assigned_channels
()¶ Returns array of channels accessible by current user.
Returns: Array of channels accessible by current user Return type: Array
fetch_action_id¶
-
Functions::
fetch_action_id
($class, $method)¶ Returns a tag in the format
{AID:class:method}
for use in the frontend. (See also EE->cp->fetch_action_id).$action_id = ee()->functions->fetch_action_id('Comment', 'insert_new_comment');
Parameters: - $class (string) – Class that contains the
$method
- $method (string) – Name of the method that has an action ID
Returns: Valid action ID tag
Return type: String
- $class (string) – Class that contains the
create_captcha¶
-
Functions::
create_captcha
($old_world = '')¶ Using a random word chosen from the array stored in the
config/captcha.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.Parameters: - $old_word (string) – Can specify the word to appear as a captcha
Returns: <img>
tagReturn type: String
sql_andor_string¶
-
Functions::
sql_andor_string
($str, $field[, $prefix = ''[, $null = FALSE]])¶ 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 = 'channel|news|sports'; $sql = "SELECT * FROM exp_channels WHERE site_id = 1 "; $sql .= ee()->functions->sql_andor_string($str, 'channel_name'); // $sql equals: // SELECT * FROM exp_channels WHERE site_id = 1 // AND channel_name = 'channel' OR channel_name = 'news' OR channel_name = 'sports'
Parameters: - $str (string) – Pipe delimited string from the tag parameter
- $field (string) – Name of the database field
- $prefix (string) – Field prefix, used when working with multiple
tables to define the table (e.g.
database_table_name.field_name
) - $null (boolean) – Allow for null values in the
$field
Returns: Partial query string containing some of the
WHERE
clauseReturn type: String
assign_variables¶
-
Functions::
assign_variables
([$str = ''[, $slash = '/']])¶ 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
orvar_pair
.Parameters: - $str (string) – String to parse
- $slash (string) – What kind of backslash is in the string (
/
or/
)
Returns: Associative array containing both
var_single
andvar_pair
Return type: Array
fetch_date_variables¶
-
Functions::
fetch_date_variables
($datestr)¶ Fetch the date format (e.g.
%Y %m %d
) from a date variable (e.g.{date format="%Y %m %d"}
).Parameters: - $datestr (string) – The string to look for a single date format in
Returns: Date format string
Return type: String
assign_parameters¶
-
Functions::
assign_parameters
($str)¶ Fetch parameters for tag
Parameters: - $str (string) – String containing tag parameters directly from the
TMPL::$tagdata
Returns: Associative array containing the tag parameters
Return type: Array
- $str (string) – String containing tag parameters directly from the
prep_conditionals¶
-
Functions::
prep_conditionals
($str, $vars[, $safety = 'n'[, $prefix = '']])¶ Parses conditionals and preps conditional for evaluation
Parameters: - $str (string) – Template
TMPL::$tagdata
to parse - $vars (array) – Associative array of conditionals to parse
- $safety (string) – Set to
'y'
to ensure that some safety checks are performed to make sure conditionals are well formed - $prefix (string) – Used when your variables have a prefix, parses both prefixed and non-prefixed variables
Returns: $str
with the conditionals from$var
parsedReturn type: String
- $str (string) – Template