Selected functions in Question2Answer

Your external code and plugins are free to use any of the 600+ functions defined within Q2A. When developing new versions of Q2A, the utmost effort is made to keep its functions backwards compatible, so that code using these functions continues to work.

A selected of the most useful functions are described below, grouped by the PHP file in the qa-include directory in which they appear. With the exception of qa-base.php, which is loaded first, you must include a file as follows before using its functions:

require_once QA_INCLUDE_DIR.'qa-XXX.php';

Many of these functions take optional additional parameters which are not shown here - please consult the source code for details. Functions marked Q2A 1.5+ were introduced in Question2Answer 1.5.

General functions in qa-base.php

  • qa_exit($reason) calls the shutdown() method of any installed process modules, passing the supplied $reason. Then it terminates execution of the PHP script with PHP's exit; command. Requires Q2A 1.5+.
  • qa_fatal_error($message) outputs and logs $message, then calls qa_exit('error'); to terminate execution.
  • qa_list_modules($type) returns an array containing the names of all installed modules of type $type.
  • qa_load_module($type, $name) returns an object belonging to the class defined in module $name of type $type, or null if it cannot be loaded. You can use this to communicate between multiple modules within a plugin, or between different plugins. Note that multiple calls to qa_load_module() will return the same object.
  • qa_load_modules_with($type, $method) returns an array of objects for the installed modules of type $type which have $method defined. Requires Q2A 1.5+. For example, $modules=qa_load_modules_with('page', 'match_request');
  • qa_html($string) returns $string escaped for output in HTML, e.g. mapping " to "
  • qa_sanitize_html($html, $linksnewwindow) returns $html after ensuring it is clear of Javascript and other possible security issues. It should be used to make the HTML provided by one user (e.g. in an editor module) safe for display to other users. If $linksnewwindow is true, then any links in the HTML will be modified to open in a new window.
  • qa_js($value) returns $value escaped for output in Javascript, including putting strings in quotes.
  • qa_request() returns the Q2A page being requested, e.g. 'tag/urgent'. It uses slash separators, independent of the URL scheme chosen. qa_request_part($part) divides the request using slashes, and returns the part indexed by $part>=0, or null if that part does not exist. qa_request_parts() returns an array of request parts. All require Q2A 1.5+.
  • qa_get($field) returns the value of URL parameter $field (from $_GET in PHP) or null if it was not present.
  • qa_post_text($field) returns the value of the POSTed $field, trimmed with \n line endings, or null if not present.
  • qa_clicked($name) returns true if the form button named $name was clicked to POST a form.
  • qa_remote_ip_address() returns the IP address making the current request, or null if unavailable. Requires Q2A 1.4.1+.
  • qa_is_human_probably() returns true if the current request appears to be from a person using a web browser, rather than a search engine bot or automated script. This assessment is based on the HTTP user agent containing a known string such as MSIE or Firefox. Note that it is perfectly possible for a malicious bot or script to masquerade as a web browser.
  • qa_is_mobile_probably() returns true if the current request appears to be from a mobile phone. This assessment is based on the presence of mobile HTTP headers or the HTTP user agent containing a mobile identifying string. Requires Q2A 1.5+.
  • qa_lang($identifier) and qa_lang_html($identifier) return a localized language phrase from the appropriate qa-lang-*.php file. For example, qa_lang('main/cancel_button') would return the phrase with key 'cancel_button' from the file qa-lang-main.php. The phrase returned by qa_lang_html() is escaped for output in HTML. From Q2A 1.5+, language files can also be registered by plugins and then accessed via these functions.
  • qa_path_to_root() returns the URL to the root of the Q2A site, relative to the currently requested page. Requires Q2A 1.5+.
  • qa_path($request) and qa_path_html($request) return the URL for Q2A page $request, relative to the currently requested page. The URL returned by qa_path_html() is escaped for output in HTML. To ensure compatibility with different Q2A URL structures, please use these functions to build URLs instead of hard-coding their structure.
  • qa_path($request, $params) and qa_path_html($request, $params) allow you to add GET-style parameters to Q2A URLs, where $params is an array of parameter name => parameter value, not yet urlencoded. Usage example:

    echo '<A HREF="'.qa_path_html('search', array('q' => 'reset password')).'">Resetting Password<A>';
  • qa_q_path($questionid, $title, $absolute, $showtype, $showid) and qa_q_path_html(...) return the URL for question $questionid which has $title as its title. If $absolute is true, this will be an absolute URL, otherwise it will be relative to the currently requested page. To link to a particular answer or comment within that question page, pass 'A' or 'C' as the $showtype and the postid of the answer or comment in $showid. Otherwise, pass null or omit these last two parameters. The URL returned by qa_q_path_html() is escaped for output in HTML. Requires Q2A 1.5+.
  • qa_self_html() returns the relative URL for the current Q2A page, preserving URL parameters, escaped for output in HTML. It is particularly useful for creating form tags, e.g. echo '<FORM METHOD="POST" ACTION="'.qa_self_html().'">';
  • qa_redirect($request) and qa_redirect($request, $params) perform an HTTP redirect to a Q2A page, specified in the same way as the parameters to qa_path().
  • qa_redirect_raw($url) performs an HTTP redirect to $url, without processing the URL in any way. Generally you should use qa_redirect() however this function can be useful for login modules.
  • qa_retrieve_url($url) returns the content of remote $url, using PHP's file_get_contents() or curl functions.
  • qa_opt($name) gets the value of the option labelled $name from Q2A's internal options storage.
  • qa_opt($name, $value) sets the option labelled $name to $value in Q2A's internal options storage. To prevent interference with Q2A or other plugins, your options should be named using a prefix which is unique to your plugin. Do not use this to store large pieces of content, since all options are retrieved for every Q2A page request - instead, look at qa-db-blobs.php.
  • qa_suspend_event_reports($suspend) suspends the reporting of events to event modules if $suspend is true, and reinstates it if $suspend is false. This might be useful if you are programmatically creating or modifying a lot of content or other database information, and want to prevent logging and other inappropriate responses to these events.
  • qa_report_event($event, $userid, $handle, $cookieid, $params) reports an event to all event modules registered by plugins. The five parameters are passed straight through to the process_event() function in each event module.

Database access in qa-db.php

  • qa_db_connection() returns the connection to the Q2A database, for use with PHP's mysql_query() function and the like.
  • qa_db_query_raw($query) runs the raw SQL in $query on the Q2A database and returns a PHP result resource. Note that if the query fails due to a MySQL error, Q2A will stop normal execution and start checking the database for problems.
  • qa_db_escape_string($string) returns $string escaped for safe inclusion in raw SQL.
  • qa_db_query_sub($query, ...) runs the SQL in $query on the Q2A database after substituting the symbols ^, # and $, returning a PHP result resource. This function is the recommended way to run queries on the Q2A database, and automatically escapes all substituted parameters for safe SQL. The ^ symbol is substituted for the appropriate Q2A table prefix set in qa-config.php, which is qa_ by default. The # and $ symbols are substituted for numerical and UTF-8 string values respectively, where these values are taken in order from the additional parameters to the function. If you want to retrieve the text from UTF-8 encoded columns from the database, you should use the BINARY modifier in front of the column name in your SQL, since Q2A does not explicitly set the character set of the database connection. Note that if the query fails due to a MySQL error, Q2A will stop normal execution and start checking the database for problems.
  • qa_db_read_all_assoc($result) takes the PHP result resource $result returned from a database query, and returns all the resulting data in a nested array. The outer array contains one array element per data row, with keys numbered from zero. Each inner array contains one element per data column, with column names in the keys.
  • qa_db_read_one_assoc($result, $allowempty) returns an array containing the first row in the PHP $result resource, with named columns. Set $allowempty to true if an empty result should not cause a fatal Q2A error.
  • qa_db_read_all_values($result) returns an array containing the first column from each row in the PHP $result resource.
  • qa_db_read_one_value($result, $allowempty) returns the first column of the first row in the PHP $result resource. Set $allowempty to true if an empty result should not cause a fatal Q2A error.
  • qa_suspend_update_counts($suspend) suspends the updating of various cached counts in the database if $suspend is true, and reinstates it if $suspend is false. This might be useful if you are programmatically creating or modifying a lot of content or other database information, and want to speed up the process. Once you have finished with the database modifications, you should use the buttons at the bottom of the 'Stats' page of the 'Admin' panel to recalculate all counts.

Cookie management in qa-app-cookies.php

  • qa_cookie_get() returns a string which identifies the user (not necessarily logged in) making the current Q2A request, if one is available from a browser cookie. Otherwise, it returns null.
  • qa_cookie_get_create() works like qa_cookie_get(), but if a cookie is not available, a new one is created, set in the user's browser, and returned from the function.

Sending notifications in qa-app-emails.php and qa-util-emailer.php

  • qa_send_notification($userid, $email, $handle, $subject, $body, $subs) sends an email to user $userid. You can provide the user's $email and/or $handle, or pass null for Q2A to retrieve these from the database. Several substitutions are performed on the $subject and $body. For example ^site_title will be replaced by the name of the Q2A site set in the admin interface, and ^handle and ^email will be replaced by the recipient's handle or email. You can also pass additional substitutions in the array parameter $subs - each key in $subs will be substituted for its corresponding value.
  • qa_suspend_notifications($suspend) suspends the sending of notifications to users if $suspend is true, or reinstates it if $suspend is false. This might be useful if you are programmatically creating or modifying content or other database information and want to avoid sending inappropriate emails.
  • qa_send_email($params) sends an email as specified by the array $params and returns whether the operation was successful from the server's perspective (this does not guarantee delivery). The $params array should contain the elements 'fromemail' (sender email), 'fromname' (sender name), 'toemail' (recipient email), 'toname' (recipient name), 'subject' (subject line), 'body' (UTF-8 encoded email body) and 'html' (true if $params['body'] is HTML-formatted, false otherwise).

Option management in qa-app-options.php

  • qa_get_options($names) returns an array mapping all the options in the $names array to their values. This may be easier than calling qa_opt() from qa-base.php many times.
  • qa_using_tags() and qa_using_categories() respectively return whether Q2A is using tags or categories to classify questions. Note that it is possible to use both tags and categories simultaneously, or to use neither.

Post management in qa-app-posts.php and qa-app-post-create.php

Note that all qa_post...() functions will send the appropriate email notifications and event reports, as well as update database indexes and counts. This can be prevented with the qa_suspend...() functions, described elsewhere on this page.

  • qa_post_create($type, $parentpostid, $title, $content, $format, $categoryid, $tags, $userid, $notify, $email) creates a new post in the database, and returns its postid. Set $type to 'Q' for a new question, 'A' for an answer, or 'C' for a comment. To queue the post for moderation (requires Q2A 1.5+), set $type to 'Q_QUEUED', 'A_QUEUED', or 'C_QUEUED' instead. For questions, set $parentpostid to the postid of the answer to which the question is related, or null if (as in most cases) the question is not related to an answer. For answers, set $parentpostid to the postid of the question being answered. For comments, set $parentpostid to the postid of the question or answer to which the comment relates. The $content and $format parameters go together - if $format is '' then $content should be in plain UTF-8 text, and if $format is 'html' then $content should be in UTF-8 HTML. Other values of $format may be allowed if an appropriate viewer module is installed. The $title, $categoryid and $tags parameters are only relevant when creating a question - $tags can either be an array of tags, or a string of tags separated by commas. The new post will be assigned to $userid if it is not null, otherwise it will be anonymous. If $notify is true then the author will be sent notifications relating to the post - either to $email if it is specified and valid, or to the current email address of $userid if $email is '@'.
  • qa_post_set_content($postid, $title, $content, $format, $tags, $notify, $email, $byuserid) changes the data stored for post $postid based on any of the $title, $content, $format, $tags, $notify and $email parameters passed which are not null. The meaning of these parameters is the same as for qa_post_create() above. Pass the identify of the user making this change in $byuserid (or null for an anonymous change).
  • qa_post_set_category($postid, $categoryid, $byuserid) changes the category of $postid to $categoryid. The category of all related posts (shown together on the same question page) will also be changed. Pass the identify of the user making this change in $byuserid (or null for an anonymous change).
  • qa_post_set_selchildid($questionid, $answerid, $byuserid) sets the selected best answer of $questionid to $answerid (or to none if $answerid is null). Pass the identify of the user in $byuserid (or null for an anonymous change).
  • qa_post_set_closed($questionid, $closed, $originalpostid, $note, $byuserid) closes $questionid if $closed is true, otherwises it reopens it (requires Q2A 1.5+). If $closed is true, pass either the $originalpostid of the question that it is a duplicate of, or a $note to explain why it's closed. The other parameter should be set to null. Pass the identify of the user closing the question in $byuserid (or null for an anonymous change).
  • qa_post_set_hidden($postid, $hidden, $byuserid) hides $postid if $hidden is true, otherwise it shows the post. If the post is waiting for moderator approval (Q2A 1.5+), $hidden=true rejects the post, and $hidden=false approves it. Pass the identify of the user making this change in $byuserid (or null for an anonymous change).
  • qa_post_delete($postid) deletes $postid from the database, hiding it first if appropriate.
  • qa_post_get_full($postid) retrieves the full information from the database for $postid, returning it in an array.
  • qa_suspend_post_indexing($suspend) suspends the indexing (and unindexing) of posts in the database if $suspend is true, and reinstates it if $suspend is false. This might be useful if you are programmatically creating or modifying a lot of content, and want to speed up the process, leaving Q2A's search results out of date. Once you have finished with the database modifications, you should use the button at the bottom of the 'Stats' page of the 'Admin' panel to reindex all posts.

User management in qa-app-users.php

  • qa_get_logged_in_userid() returns the userid of the currently logged in Q2A user, or null if no user is logged in.
  • qa_get_logged_in_handle() returns the handle/username of the currently logged in user, or null if no user is logged in.
  • qa_get_logged_in_email() returns the email address of the currently logged in user, or null if no user is logged in.
  • qa_get_logged_in_flags() returns flags for the currently logged in user, or null if no user is logged in. The flag bit masks are defined in the QA_USER_FLAGS_* constants at the top of qa-app-users.php. If the QA_USER_FLAGS_USER_BLOCKED or QA_USER_FLAGS_MUST_CONFIRM (Q2A 1.5+) bit is set, the user should be prevented from write actions.
  • qa_get_logged_in_level() returns a number representing the privilege level of the currently logged in user, or null if no user is logged in. You can compare this against the QA_USER_LEVEL_* constants defined at the top of qa-app-users.php.
  • qa_get_logged_in_points() returns the points of the currently logged in user, or null if no user is logged in.

Large object management in qa-db-blobs.php and qa-app-blobs.php

  • qa_db_blob_create($content, $format) creates a new binary large object (BLOB) in the Q2A database and returns its $blobid, or null upon failure. The $content may contain up to 16 Mb of arbitrary data in any format, and the $format should contain the appropriate corresponding file extension, e.g. 'jpeg', 'gif', 'png', 'txt', 'doc', 'xls', 'pdf'. From Q2A 1.4 beta, qa_db_blob_create() takes optional additional parameters enabling the source of the BLOB to be recorded.
  • qa_db_blob_read($blobid) reads the object identified by $blobid from the database and returns it in an array with the keys 'content' and 'format'. If the BLOB does not exist, it returns null instead.
  • qa_db_blob_delete($blobid) deletes the object identified by $blobid from the database, if it exists.
  • qa_db_blob_exists($blobid) returns whether the database contains an object identified by $blobid.
  • qa_get_blob_url($blobid, $absolute) returns a URL which can be used to view or download $blobid. If $absolute is false, this URL will be relative to the current Q2A page being requested, otherwise the URL will be absolute.
  • qa_get_max_blob_upload_size() returns the maximum size in bytes of a BLOB that can be uploaded by a user, taking into account database constraints and PHP's upload_max_filesize parameter.

Metadata management in qa-db-metas.php (Q2A 1.5+)

  • qa_db_usermeta_set($userid, $key, $value) sets metadata $key for user $userid to $value. Each user can only have a single piece of metadata with a particular key. Keys beginning with qa_ are reserved for the Q2A core.
  • qa_db_usermeta_clear($userid, $key) clears metadata $key for user $userid. An array of keys can also be passed in $key, in which case the metadata for every key is removed.
  • qa_db_usermeta_get($userid, $key) returns the value of metadata $key for user $userid, or null if none exists. An array of keys can also be passed in $key, in which case an array is returned which maps metadata keys to values.
  • The corresponding functions qa_db_postmeta_set($postid, $key, $value), qa_db_postmeta_clear($postid, $key) and qa_db_postmeta_get($postid, $key) work the same way for metadata on individual posts.
  • The functions qa_db_categorymeta_set($categoryid, $key, $value), qa_db_categorymeta_clear($categoryid, $key) and qa_db_categorymeta_get($categoryid, $key) work the same way for metadata on categories.
  • The functions qa_db_tagmeta_set($tag, $key, $value), qa_db_tagmeta_clear($tag, $key) and qa_db_tagmeta_get($tag, $key) work the same way for metadata on tags, where $tag is the text of a tag.

User notice management in qa-db-notices.php (Q2A 1.5+)

  • qa_db_usernotice_create($userid, $content, $format, $tags) creates a new notice to be displayed to user $userid and returns its noticeid. The notice will appear at the top of every page until the user dismisses it - this also deletes it from the database. The $content and $format parameters describe the content of the notice together - if $format is '' then $content should be in plain UTF-8 text, and if $format is 'html' then $content should be in UTF-8 HTML. You can use the $tags parameter to add some additional information to the notice which is stored in the database but not displayed to the user.
  • qa_db_usernotice_delete($userid, $noticeid) deletes notice $noticeid for user $userid, if it exists in the database.
  • qa_db_usernotices_list($userid) returns a nested array describing the notices which are being stored and displayed for user $userid. Each element in the returned array contains an array with three labelled values - 'noticeid', 'tags' (as passed when the notice was created) and 'created' (a Unix timestamp of the notice creation time).

Array manipulation in qa-util-sort.php

  • qa_sort_by(&$array, $by1) sorts the nested array $array in place, by comparing the sub-element with key $by1 of each inner array within $array. For example, if $array=array(array('n'=>1,'w'=>'dog'), array('n'=>2,'w'=>'cat')) then qa_sort_by(&$array, 'n') would leave $array unchanged, whereas qa_sort_by(&$array, 'w') would reverse its order. An additional parameter $by2 can also be passed, to allow an additional comparison in cases where the first key matches.
  • qa_array_insert(&$array, $beforekey, $addelements) inserts all the elements from the array $addelements into $array, preserving all keys in both arrays. The new elements are positioned together before key $beforekey in $array and their order is preserved. If $beforekey cannot be found in $array, the elements are appended at the end instead. Requires Q2A 1.4.2+.

String manipulation in qa-util-string.php

  • qa_string_to_words($string) breaks $string up into words, and returns them in lower case in an array. The function contains several additional parameters that provide more control over this process - see the source code.
  • qa_tags_to_tagstring($tags) takes an array of tags, and returns the string to be stored for those tags in the database.
  • qa_tagstring_to_tags($tags) takes a list of tags from the database, and returns it as an array of tags.
Question2Answer © Gideon Greenspan 2013