Some rare documentation for plugin authors

Apr 24, 06:20 PM

For my own reference, I went through Textpattern’s database library and made a list of the functions with a short description for each. I suspect this could be useful for others who need to extend Textpattern.

This is every function in txplib_db.php, as of version 4.0.8:


safe_pfx($table):
Adds the table prefix defined for this instance of Textpattern to $table and wraps the table name in backticks.

safe_pfx_j($table):
Does the same as safe_pfx(), but for a comma-separated list of tables.

safe_query($q='',$debug='',$unbuf=''):
Run a query and return the result handle or false. If $debug is true, the query will be logged. safe_query() will warn if the query fails and the current page is the admin interface or the site is currently in “debug” or “testing” mode. If $unbuf is true, use mysql_unbuffered_query() to get the result, otherwise use mysql_query(). safe_query() seems to be mainly intended as a resource for the other functions in this library, rather than as something to be called directly—(nearly) all of the functions below call safe_query, and the $debug argument is always just passed to it.

safe_delete($table, $where, $debug=''):
Deletes a row or rows from $table where $where.

safe_update($table, $set, $where, $debug=''):
"UPDATE $table SET $set WHERE $where".

safe_insert($table,$set,$debug=''):
Again using safe_query(), inserts a row into $table using data $set.

safe_upsert($table,$set,$where,$debug=''):
Tries to update a table row with the arguments provided, if that fails it will insert a new row.

safe_alter($table, $alter, $debug=''):
ALTERs $table. Use this to modify an existing table in the database (adding a new field, for example).

safe_optimize($table, $debug=''):
OPTIMIZEs $table. Probably not useful for plugin authors.

safe_repair($table, $debug=''):
REPAIRs $table. Again, probably (hopefully!) not useful for plugin authors.

safe_field($thing, $table, $where, $debug=''):
Runs the query provided (”SELECT $thing FROM $table WHERE $where“) and returns the first cell of the first result row.

safe_column($thing, $table, $where, $debug=''):
Returns a (number-indexed) array containing the first field from the result of the query given. If $thing includes more than one field, all of them after the first are ignored.

safe_row($things, $table, $where, $debug=''):
Returns an associative array of the first row of the results from the query generated from the arguments.

safe_rows($things, $table, $where, $debug=''):
Returns an array of associative arrays containing the complete results of the query generated from the arguments.

safe_rows_start($things, $table, $where, $debug=''):
Returns a query resource handle, which can be used to read data directly or passed through nextRow() (below), which will automatically run mysql_free_result() after the last row is returned.

safe_count($table, $where, $debug=''):
Returns the number of rows in $table matching the query $where.

safe_show($thing, $table, $debug=''):
Runs a MySQL SHOW query. Note that the query takes the format of "SHOW $thing FROM $table"—this will only work for a few possible values of $thing.

fetch($col,$table,$key,$val,$debug=''):
Returns the first row from a query: "SELECT $col FROM $table WHERE $key = $val". Very much like safe_row, except it builds the (simple) SQL WHERE clause for you.

getRow($query,$debug=''):
Yet another way to get the first row of a result set. Used as the back end of safe_row()

getRows($query,$debug=''):
Returns a query result as an array.

startRows($query,$debug=''):
Returns a MySQL result resource. Called by safe_rows_start() to do its thing.

nextRow($r):
$r is a result resource. This function returns the next row, or, if we’re at the end of the result set, false. It also frees the memory used by $r when it reaches the end.

numRows($r):
Just returns the number of rows in the query.

getThing($query,$debug=''):
Like safe_field(), returns the first cell of the first result row.

getThings($query,$debug=''):
Returns the first column of results of $query in a number-indexed array.

getCount($table,$where,$debug=''):
Returns a row count of the query.

getTree($root, $type, $where='1=1', $tbl='txp_category'):
Returns all of the children of category $root (if you want the entire hierarchy tree, set this to 'root'). $type is one of ‘file’, ‘image’, ‘link’, or ‘article’. The returned array includes (for each category):
  • 'id': The category’s primary key (an auto-increment);
  • 'name': The category’s url-friendly name;
  • 'title': The human-readable name;
  • 'level': The number of steps between this category and $root;
  • 'children': The number of children this category has; and
  • 'parent': The category’s parent.

getTreePath($target, $type, $tbl='txp_category'):
Gets all the parents of category $target. The return value is the same as for getTree(), except that the 'parent' field isn’t included.

rebuild_tree($parent, $left, $type, $tbl='txp_category') and rebuild_tree_full($type, $tbl='txp_category'):
Rebuild the category hierarchy tree. Use rebuild_tree_full() instead of rebuild_tree() to rebuild an entire tree from category 'root'

get_prefs():
Retrieves a list of preferences from the database. Shouldn’t be necessary for plugin writers—you can read the $prefs global variable instead.

db_down():
Return a MySQL error message, ready to be sent to the browser.