ITools - A simple support library for PHP

ITools is a collection of PHP functions and classes which make a few common tasks in PHP easier. It works in PHP 5 and up.

Our examples omit array() around function parameters and use dangling commas. To get that, you can either use our just-in-time syntax converter or use our patch for PHP (see http://cschneid.com/php/ for info). To use the syntax converter, see the chapter about it_auto_prepend.php below.

it_auto_prepend.php - ITools environment (optional)

If you include this with the PHP auto_prepend_file ini setting you get the following benefits:

Includes all the ITools functionality
auto_prepend.php is included for each directory in the include path.
Automatic syntax conversion is enabled if you have a vanilla PHP without our syntax patch installed. NOTE: This may need manual configuration on shared hosting
An autoloader for classes is installed, you don't need to require any files it looks for foo.class if you access class foo).
$GLOBALS['IT_HOME'] is set to one level above the DOCUMENT_ROOT in web mode, one level above the script for CLI mode: This allows access to data directories from web and CLI mode alike.

Example:

  # Put this line in .htaccess or httpd.conf to set up ITools environment
  php_value auto_prepend_file YOUR_PATH_TO_ITOOLS/it_auto_prepend.php

it_html - HTML output generation

it_html creates a global function for each common html tag. Those functions accept variable arguments, key=>value pairs are considered attributes.

Example:

  new it_html;    # Not necessary if using it_auto_prepend.php
  echo html(
    head('title' => "welcome earth"),
    body(
      p('style' => "margin:1em",
        a('href' => U("http://google.com/search", 'q' => "Hello World"), "Hello World"),
      ),
    ),
  );

Functions:

new it_html($config)	create global functions, choose (x)html style
div($attributes, $content)	return a <div> with attributes and content
html($params, $content)	return a <html> but adds correct doctype
head($params, $content)	return a <head> but needs special params
select($tags, $options, $selected)	build a html select from an array
tag($tag, $content)	create arbitrary <$tag>
Q($str)	html encode a value, roughly like htmlentities
U($arr)	create a valid url from strings and key=>value
it_html::sanitize($html)	remove dangerous tags from html code

it_dbi - Database access

The dbi object is a simple mysql interface. For each table in your database, a class is created automatically. Queries are encoded as arrays which ensures correct quoting, see select(). Errors are by default reported within dbi.

Example:

  it_dbi::createclasses();    # Not necessary if using it_auto_prepend.php
  $record = new T_Customers('ID' => 'mueller');
  $record->update('email' => "mueller@spam.com");
  $response = "Email added for $record->name";
  # Using Iterators (PHP 5+ only):
  foreach (new T_Customers as $customer) { ... }    # Iterate all customers
  foreach (new T_Customers('age' => 42) as $customer) { ... }
  foreach (new T_Customers as $id => $customer) { ... }    # $id = $customer->_key
  # ... you can iterate over any query (also multiple times):
  $customers->select('age' => 42);
  foreach ($customers as $customer) { foo($customer); }
  foreach ($customers as $customer) { bar($customer); }

Functions:

it_dbi::createclasses($config)	create database objects for each table name
$t = new Tablename($query)	return a dbi object, executes optional select
$t->select($query)	read first result of (encoded) query into t.
$t->iterate()	advance to next result
$t->update($fields)	update selected record from key=>value pairs
$t->insert($fields)	insert a new record from key=>value pairs
$t->replace($fields)	replace a new record from key=>value pairs
$t->delete($query)	delete current record or those found by query
$t->query($sqlquery)	execute a raw SQL query on db connection

it_text - Translation support

it_text finds the best language to use from browser and override settings. It then reads texts.php in the format documented in the constructor. You can then use T() to translate a label. Unknown labels are reported using it::error()

Example:

  echo T('hello') . ' ' . Q($customer->name);
  echo ET('chainletter', 'name' => Q($customer->name));

Functions:

new it_text($config)	read texts. usually called implicitly
T($label)	return translated $label
ET($label, $values)	return translated $label w/ values replaced
T_lang()	returns current language
T_set_language($language)	sets a new language
T_exists($label)	returns whether a label is defined

it_debug - Debug support

it_debug is used for debugging. The function ED($foo, $bar) echoes the values of $foo and $bar AND prepends it with the names of the variables. EDX() does the same and exits. EDC('verbose', $foo) only echoes if $GLOBALS['debug_verbose'] is set. it_debug::backtrace() outputs a compact stackdump.

Example:

  ED($foo, $bar);  # echoes name and value of $foo and $bar
  EDC('verbose', $foo);

Functions:

ED($args...)	echoes names and values of all args
EDX($args...)	echoes names and values of all args and exits
EDC('foo', $var...)	echoes only if $GLOBALS['debug_foo'] is set
D($args...)	returns formatted names and values of params
it_debug::backtrace($skip)	prints short backtrace, skipping $skip levels

it.class - Tool functions

it.class provides various statically callable functions. The main groups are:

Much simpler perl regex matching (no delimiters, matches returned directly as scalar or array, case insensitive, locale support) and a multi-pattern replacement function.
Better error functions: stack and variable dumps added to error messages, error messages mailed if display_errors is off. Extra parameter allow the filtering of sporadic errors.
Better shell support, specifically a command line parser and an exec function that handles quoting.

Example:

  $from = it::match('From: (.*)', $mail);
  $page = it::replace('<.*?>' => '', ' +' => ' ', $page);
  it::error('title'=>"cannot connect", 'id'=>"db"); # suppress sporadic errors
  it::fatal("internal error");
  $diff = it::exec("diff -wu {old} {new}", 'old' => $old, 'new' => $new);
  it::imageconvert('in' => "src.jpg", 'out' => "dst.jpg", 'size' => "80x80");

Functions:

it::match($pattern, $subject, $opts)	find pattern in subject using opts; return matches
it::replace($replace, $subject, $opts)	replace patterns in subject; return result
it::error($info)	print or mail error message
it::fatal($info)	print or mail error message, then exit
it::bail($message)	print message to stderr, exit with errcode
it::exec($command, $values)	execute command, return output
it::getopt($usage)	parse (or print) usage, return options,
it::gets()	fetch next line from stdin or named arg
it::imageconvert($params)	Convert image using ImageMagick convert
it::log($fn, $data, $data...)	Append data (separated by tabs) to log/$fn-$date
it::map($expr, $array)	Apply php expression to array members & return

it_url - URL handling

Helper functions dealing with URLs.

Example:

  $filename = it_url::get_cache(
    'url' => "http://static.php.net/www.php.net/images/php.gif",
    'timeout' => 5,
    'cachedir' => $_SERVER['DOCUMENT_ROOT'] . "/cache",
  );

Functions:

it_url::get($params)	performs GET/POST requests to web servers
it_url::get_cache($params)	performs GET/POST and caches the result

it_user - Session handling

This allows maintaining session cookies and authentication status for users. Not documented yet, check the source.

it_xml - XML parser

This will parse an XML string and returns a tree of PHP objects; similar to simplexml, supports a streaming mode for huge XML files. Not documented yet, check the source.