From b652c6750107110c23748986cb05054979f5192e Mon Sep 17 00:00:00 2001
From: Christian Schneider
Date: Wed, 10 Oct 2007 16:16:01 +0000
Subject: Various README enhancements
---
README | 121 ++++++++++++++++++++++++++++++++++++++++-------------------------
1 file changed, 74 insertions(+), 47 deletions(-)
(limited to 'README')
diff --git a/README b/README
index dc4c9ea..8913b76 100644
--- a/README
+++ b/README
@@ -1,81 +1,97 @@
+ITools - A simple support library for PHP
+=========================================
-itools is a collection of php functions and objects which should make a few common tasks in php easier. It is php 4 and php 5 compatible. The methods are documented in the source code.
+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 or our just-in-time syntax converter.
+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.
+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!"),
+ 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) -- returns a <div> with attributes and content
- html($params, $content) -- returns a <html> but adds correct doctype in front
- head($params, $content) -- returns a <head> but only supports special params
- select($tags, $opts, $sel) -- builds a html select from an array
- tag($tag,$content) -- like the other tag funcs but uses arbitrary tagname
- Q($str) -- html encodes a value, roughly like htmlentities()
- U($arr) -- creates a valid url from strings and key=>value
- it_html::sanitize() -- removes dangerous tags from html code
+ 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 enables correct quoting, see select(). Errors are by default handled within dbi.
+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;
+ $response = "Email added for $record->name";
Functions:
- it_dbi::createclasses($conf) -- creates database objects for each table name
- $t = new Tablename($query) -- returns a dbi object, executing optional select
- $t->select($query) -- reads first result of (array encoded) query into t.
- $t->iterate() -- advances to next result
- $t->update($fields) -- updates a selected record based on key=>value pairs
- $t->insert($fields) -- inserts a new record from key=>value pairs
- $t->replace($fields) -- replaces a new record from key=>value pairs
- $t->delete($query) -- deletes current record or those found by query
- $t->query($rawquery) -- execute a raw query on db connection
+ 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 array('label'=>array('lang'=>"translated text")). You can then use T() to translate a label. Unknown labels are logged in text_log.
+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($conf) -- reads texts. doesn't need to be called by default
- T($label) -- returns translation of $label
- ET($label, $values) -- returns translation of $label with variables replaced
+ 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($lang) -- sets a new 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.
+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
@@ -93,25 +109,33 @@ Functions:
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
+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");
- it::error('title'=>"cannot connect", 'id'=>"db"); # suppresses sporadic errors
+ $diff = it::exec("diff -wu {old} {new}", 'old' => $old, 'new' => $new);
+ it::imageconvert('in' => "src.jpg", 'out' => "dst.jpg", 'size' => "80x80");
Functions:
- it::match($patt, $subj, $o) -- finds patt in subj using options and returns match(es)
- it::replace($rep, $subj, $o) -- replaces patterns in rep in subj and returns result
- it::error($arg) -- prints or mails error message; more opts if arg is array
- it::fatal($title) -- same as it::error but exits
- it::bail($msg) -- print message to stderr and exit with error code
- it::exec($cmd, $values) -- execute command, return output
- it::getopt($usage) -- parse (or print) usage, return options,
- it::gets() -- fetch next line from stdin or named arg (must call it::getopt first)
+ 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
@@ -127,14 +151,17 @@ Example:
);
Functions:
- it_url::get($params) -- performs GET and POST requests to web servers
- it_url::get_cache($params) -- does the same but caches the result; supports filters
+ 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.
+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 php5 but works in php4. Not documented yet, check the source.
+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