ITools - A simple support library for PHP
=========================================
Home: http://itools.search.ch/
License: http://itools.search.ch/itools/live/COPYING
Installing: svn co http://itools.search.ch/itools/live itools
Reference: http://itools.search.ch/(function | class | class/function)
Tutorial video: http://itools.search.ch/2007-11-14-itools-demo.mov
ITools is a collection of PHP functions and classes which make a few common
tasks in PHP easier. It works in PHP 4 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:
a) Includes all the ITools functionality
b) auto_prepend.php is included for each directory in the include path.
c) 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
d) If you run PHP 5 an autoloader for classes is installed, you don't need
to require any files (it looks for foo.class if you access class foo).
e) $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;
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();
$record = new T_Customers('ID' => 'mueller');
$record->update('email' => "mueller@spam.com");
$response = "Email added for $record->name";
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 logged in text_log.
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) outputs echoes the
values of $foo and $bar AND prepends it with the names of the variables. EDX()
does the same and exists. EDC('verbose', $foo) only echoes if
$GLOBALS['debug_verbose'] is set. it_debug::backtrace() outputs a compact
stackdump.
Example:
ED($foo, $bar); # outputs 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:
a) Much simpler perl regex matching (no delimiters, matches returned directly
as scalar or array, case insensitive, locale support) and a multi-pattern
replacement function.
b) 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.
c) 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_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 in PHP 5 but works in PHP 4 and supports a streaming mode for huge
XML files. Not documented yet, check the source.