EWE Programming documentation

3.5. Class and Function Reference

This document describes the classes and functions available to web developers on EWE sites. Each class and function are listed with a description and the name of the file in which it is defined.

3.5.1. Functions

This section describes the functions provided by EWE.

3.5.1.1. badword

File: base/badword.php
Format: badword($word)
where $word is the word to check.
Example: if(badword($word)) break;

This function returns TRUE if the passed value is an obscene word. This function is used to check user names, etc., to help keep sites G-rated. It checks for leet and other variants.

3.5.1.2. clear_error

File: base/Errors.php
Format: clear_error()
Example: clear_error();

This function clears the text set by set_error_text().

3.5.1.3. db_data_seek

File: base/connect.php
Format: $result = db_data_seek($res, $offset)
where $res is the result from the last database query and $offset is the offset to position to.
Example: db_data_seek($res, 0); // Reset to first row

This function is a wrapper for the primary database data_seek() method, which sets the result pointer to the specified offset. It is recommended that you obtain a database instance with Databases::get_database, and use that instance's data_seek() method.

3.5.1.4. db_fetch_assoc

File: base/connect.php
Format: $result = db_fetch_assoc($res)
where $res is the result from the last query.
Example: $row = db_fetch_assoc($res);

This function is a wrapper for the primary database fetch_assoc() method, which returns the next row of the result set associated with $res. It is recommended that you obtain a database instance with Databases::get_database, and use that instance's fetch_assoc() method.

3.5.1.5. db_insert_id

File: base/connect.php
Format: $result = db_insert_id()
Example: $id = db_insert_id();

This function is a wrapper for the primary database insert_id() method, which returns the ID of the last insert operation. It is recommended that you obtain a database instance with Databases::get_database, and use that instance's insert_id() method.

3.5.1.6. db_num_rows

File: base/connect.php
Format: $result = db_num_rows($r)
where $r is the database resource from the last query.
Example: $count = db_num_rows($res);

This function is a wrapper for the primary database num_rows() method, which returns the number of rows affect, or returned, for the last database operation associated with the $res result. It is recommended that you obtain a database instance with Databases::get_database, and use that instance's num_rows() method.

3.5.1.7. db_query

File: base/connect.php
Format: $result = db_query(&$sql,$site=0)
where $sql is the SQL statement to execute and $site is the site ID.
Example: if(!$res = db_query($sql)) {echo 'Database query error'};

This function is a wrapper for the primary database db_query() method, which does a database query operation, returning the result.

3.5.1.8. db_real_escape_string

File: base/connect.php
Format: $result = db_real_escape_string($str)
where $str is the string to escape
Example: $str = db_real_escape_string($str);

This function is a wrapper for the primary database real_escape_string method, which escapes a string to make it suitable for inclusion in a database insertion operation. It is recommended that you obtain a database instance with Databases::get_database, and use that instance's real_escape_string() method.

3.5.1.9. display_any_error

File: base/Errors.php
Format: display_any_error()
Example: display_any_error();

If there is currently an error set (via set_error or set_error_text), this function writes out the error text. Otherwise, it does nothing.

3.5.1.10. Do_Output

File: base/Utility.php
Format: Do_Output($text)
$text is the text to output.
Example: Do_Output('Reached point X');

This function writes output, and flushes the output buffer. $text is the value to output. This function is primarily used for debugging purposes.

3.5.1.11. Enforce_Login

File: base/prepare.php
Format: Enforce_Login(siteid='')
where "siteid" is the site
Example: Enforce_Login();

This function ensures that the user is logged in to the specified site. If the site isn't specified, the current site is used. If not logged in, the user is redirected to the login page.

3.5.1.12. Enforce_Privilege

File: base/prepare.php
Format: Enforce_Privilege($priv,$module,$siteid)
where $priv is the privilege, $module is the module ID, and $siteid is the site ID.
Example: Enforce_Privilege($priv,$module,$siteid);

This function ensures that the user is logged in and has the specified privilege. If the user isn't logged in, or logged in and without the specified privilege, the user is redirected to the login page. $priv is the privilege to check for. $module is the module whose privilege is to be checked. $site is the site to be checked, or null if not site-specific.

3.5.1.13. Enter_Critical

File: base/Common.php
Format: Enter_Critical()
Example: Enter_Critical();

This function clears garbage collection and disables it so that the following code is not interrupted with garbage collection cycles. Exit_Critical() should be used to turn garbage collection back on as soon as possible.

3.5.1.14. ert

File: base/Errors.php
Format: $result = ert($err)
$err is the error value to return the text for.
Example: echo ert($result);

This function returns text for the passed EWE error.

3.5.1.15. Exit_Critical

File: base/Common.php
Format: Exit_Critical()
Example: Exit_Critical();

This function turns garbage collection back on after a call to Enter_Critical.

3.5.1.16. fast_db_query

File: base/connect.php
Format: $result = fast_db_query(&$sql)
where $sql is the SQL statement to execute.
Example: if(!$res=fast_db_query($sql) {echo 'Database query error';}

This function is a wrapper for the default database fast_db_query method, which does a database query operation, returning the result. This differs from the db_query() method in that it doesn't log any failures.

3.5.1.17. get_and_remove_parameter

File: base/Common.php
Format: get_and_remove_parameter($name,$default='',$type=EWEParameterType_String)
$name is the parameter name, $default is the default value, and $type is the required data type
Example: $uid=get_and_remove_parameter('uid',-1,EWEParameterType_Numeric);

This function returns the parameter with the given name, as per the get_parameter() function. If the value is stored in the $_SESSION['parameters'] array, it is removed.

Constant	Meaning
EWEParameterType_String	Value can be anything.
EWEParameterType_Numeric	Value must be numeric.

3.5.1.18. get_database

File: base/connect.php
Format: $result = get_database($name)
where $name is the database name.
Example: $db=get_database($name)

This function returns a database instance for the specified database set name. If the database set is not defined, the primary database instance is returned.

3.5.1.19. get_default_site

File: classes/Sites.php
Format: $result = get_default_site()
Example: $def=get_default_site()

This function returns the ID of the default site. The result has no meaning if no sites have been added.

3.5.1.20. get_default_site

File: classes/Sites.php
Format: $result = get_default_site()
Example: $site=get_default_site();

This function returns the site ID of the default site.

3.5.1.21. get_error_text

File: base/Errors.php
Format: $result = get_error_text()
Example: $errtext=get_error_text();

This function returns the text which was last set with the set_error_text() function.

3.5.1.22. get_parameter

File: base/Common.php
Format: $result = get_parameter($name,$default='',$type=EWEParameterType_String)
where $name is the parameter name, $default is the default value if the parameter isn't provided, $type is the data type (see below).
or EWEParameterType_Numeric
Example: $uid=get_parameter('uid',-1,EWEParameterType_Numeric);

This function returns the parameter with the given name. The function first checks $_SESSION['parameters'], then checks $_POST[], then checks $_GET[]. If the name doesn't exist, the default value is returned. If the type is EWEParameterType_Numeric and the value isn't numeric, the default value is returned.

Constant	Meaning
EWEParameterType_String	Value can be anything.
EWEParameterType_Numeric	Value must be numeric.

3.5.1.23. get_site_from_url

File: base/Sites.php
Format: $result = get_site_from_url()
Example: $site = get_site_from_url();

This function returns the ID of the site associated with the current URL. If no matching site is found, the default site is returned.

3.5.1.24. getLastPHPError

File: base/Errors.php
Format: $result = getLastPHPError()
Example: $text = getLastPHPError();

This function returns the text of the last PHP error. Using this function also clears the PHP error, so if you want to use the value more than once, you should save it to a variable and use that variable instead of making multiple calls to the function. Once cleared, the function will return an empty string until another PHP error occurs.

3.5.1.25. is_error

File: base/Errors.php
Format: $result = is_error($res)
Example: if(is_error($result)) {echo ert($result);}

This function returns TRUE if the passed value is a EWE error.

3.5.1.26. lock_table

File: base/connect.php
Format: lock_table($table1, $table2)
Example: lock_table('mytable', '');

This function locks the specified tables in the primary database. $table2 may be a zero-length string if only one table is to be locked. It is recommended that you obtain a database instance with Databases::get_database, and use that instance's lock_table() method.

3.5.1.27. make_error

File: base/Errors.php
Format: $result = make_error($moduleID,$code)
where $moduleID is the module ID and $code is the error code.
Example: $err = make_error($module,$error);

This function returns a EWE error consisting of the specified module ID and error code.

3.5.1.28. make_SQL_error

File: base/Errors.php
Format: $result = make_SQL_error($code,$text)
where $code is the SQL error code and $text is the error text.
Example: $err = make_SQL_error(mysqli_errno($link),mysqli_error($tlink));

This function returns a EWE error for the specified mysql error.

3.5.1.29. normalize_ip

File: base/Common.php
Format: $result = normalize_ip($ip)
Example: $ip = normalize_ip($ip);

This function normalizes an IP4 or IP6 address.

3.5.1.30. Normalize_Word

File: base/badword.php
Format: $result = Normalize_Word($word)
Example: $word = Normalize_Word($word);

This function takes a word, convert it to uppercase and del-leetifies it. Any non-alpha values are converted to dashes. It also does some phonetic normalization. The modified string is returned.

3.5.1.31. present_file

File: classes/Redirection.php
Format: present_file($name)
where $name is a file name including the full directory path.
Example: present_file($name);

This function displays the specified file, including appropriate headers.

3.5.1.32. Relative_Path

File: base/Common.php
Format: $result = Relative_Path($full)
where $full is a full directory path.
Example: $text = Relative_Path($dir);

This function takes a full path and returns a path relative to the document root.

3.5.1.33. readfile_chunked

File: base/Common.php
Format: $result = readfile_chunked($f)
where $f is the file to read.
Example: $text = readfile_chunked($file);

This function works like readfile() except that it reads the specified file in chunks to avoid problems that can sometimes occur with readfile().

3.5.1.34. Redirect

File: base/Common.php
Format: Redirect($target)
where $target is the url to redirect to.
Example: Redirect($dest);

This function redirects via header() and exits. If $target is missing "Location:" at the front, that is added before calling header(). Like header(), this cannot be used after text has been sent to the browser.

3.5.1.35. select_selected

File: base/Utility.php
Format: $result = select_selected($HTML,$ID)
where $HTML is the HTML selection statement and $ID is the option value to match.
Example: echo select_selected($html,'1');

This function takes an HTML selection statement and marks the option matching $ID as the selected item. The modified string is returned.

3.5.1.36. send_email

File: base/Common.php
Format: send_email($email,$subject,$message{,$from,$html})
where "$email" is the destination email address, "$subject" is the email subject, "$message" is the message text, "$from" is the email address source of the email, and "$html" is TRUE if the message is HTML text instead of plain text.
Example: send_email($useremail,'A message for you',$msg);

This function sends an email to the specified email with the given subject and message text. Note that you must have email properly installed on your server or using this message will result in an error. Note that the subject and message must comply with the RFC 2047 specification. If $from is not supplied, or is empty, the from will be of the form: donotreply@domain. The message text is assumed to be plain text. If you want to send HTML text, pass TRUE for the $html argument. The function returns FALSE if the send fails.

3.5.1.37. set_error

File: base/Errors.php
Format: set_error($err)
Example: set_error($res);

This function sets the session error to the specified value. if the passed value is not an EWE error, the function does nothing.

3.5.1.38. set_error_text

File: base/Errors.php
Format: set_error_text($errtext)
Example: set_error_text('You must supply an email');

This function sets the session error text to the specified version. This can be retrieved with the get_error_text() function and cleared with clear_error().

3.5.1.39. set_parameters

File: base/Common.php
Format: set_parameter($name,$value)
where "$name" is the parameter name and "$value" is the value to set the parameter to.
Example: set_parameter('index',$index);

This function changes a value to the session parameter list. $name is the name of the parameter and $value is the value for the parameter.

3.5.1.40. Show_Data

File: base/Common.php
Format: Show_Data($var,$doindent=TRUE,$level=0)
where "$var" is the variable to display, "$doindent" indicates whether or not to indent sub-levels of the data, and "$level" is the level of indentation for the top-level of the data.
Example: Show_Data($list);

This function takes a variable and outputs its contents. If it is an object or class, the contents are displayed. Each level is indended if $doindent is true, and $level is how deeply to indent the outermost level.

3.5.1.41. SQL_error

File: base/connect.php
Format: $result = SQL_error()
Example: $err = SQL_error();

This function is a wrapper for the default database error() method. It returns a EWE error for the last database operation.

3.5.1.42. unlock_tables

File: base/connect.php
Format: unlock_tables()
Example: unlock_tables();

This function unlocks all tables locked via lock_tables() in the primary database. It is recommended that you obtain a database instance with Databases::get_database, and use that instance's unlock_tables() method.

3.5.1.43. upload_ert

File: base/Errors.php
Format: $result = upload_ert($err)
where $err is the error value from a failed upload.
Example: $errtext = upload_ert($res);

This function returns the text for the specified upload error code.

3.5.2. Classes

EWE classes reside in files in the EWE classes folder. These classes provide the interface to EWE data, hiding implementation details and keeping the data consistent. PHP pages for a EWE site should never directly access the standard EWE tables. Instead these classes should be used.