ITools - A simple support library for PHP

Home: https://itools.search.ch/

License: https://itools.search.ch/git/itools.git/plain/COPYING

Installing: git clone https://itools.search.ch/git/itools.git

Reference: https://itools.search.ch/

Tutorial video: https://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 7.0 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 https://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:

  1. Includes all the ITools functionality
  2. auto_prepend.php is included for each directory in the include path.
  3. 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
  4. An autoloader for classes is installed, you don't need to require any files it looks for foo.class if you access class foo).
  5. $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("https://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. If "dyncols" exists in schema, unknown columns are mapped to a dynamic column.

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:
  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->store($fields) create a record or update efficiently if exists
$t->delete($query) delete current record or those found by query
$t->query($sqlquery) execute a raw SQL query on db connection
$t = Tablename::get($id) return valid object loaded with record $id or null

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 T('greeting', 'name' => $customer->name);

Functions:

new it_text($config) read texts. usually called implicitly
T($label, $values) return translated $label w/ quoted values replaced
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:

  1. Much simpler perl regex matching (no delimiters, matches returned directly as scalar or array, case insensitive, locale support) and a multi-pattern replacement function.
  2. 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.
  3. 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' => "https://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.