From 35fe33f7364329dacf415c950bff01b6de9ef88e Mon Sep 17 00:00:00 2001 From: Christian Schneider Date: Thu, 11 Oct 2007 00:39:30 +0000 Subject: Populated release branch --- README | 167 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..8913b76 --- /dev/null +++ b/README @@ -0,0 +1,167 @@ +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 4 and up. Typical tasks should become +easy enough to remove the need for a framework. + +Note: Our examples omit array() around function parameters and use dangling +commas. If you want to do that, you either need our PHP patch (see +http://cschneid.com/php/ for infos and the patch) or our just-in-time syntax +converter. + + +it_html - HTML output generation +-------------------------------- +it_html creates a global function for each common html tag. Those functions +accept variable arguments, key=>value pairs as considered attributes. + +Example: + new it_html; + echo html( + head('title' => "welcome earth"), + body( + p('style' => "margin:1em", + a('href' => U("http://google.com/", 'q' => "Hello World"), "Hello World"), + ), + ), + ); + +Functions: + new it_html($config) -- create global functions, choose (x)html style + div($attributes, $content) -- return a
with attributes and content + html($params, $content) -- return a but adds correct doctype + head($params, $content) -- return a 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($confg) -- 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. -- cgit v1.2.3