Docs for page AWLUtilities.php

## /AWLUtilities.php

Description

Utility functions of a general nature which are used by most AWL library classes.

- author: Andrew McMillan <andrew@mcmillan.net.nz>
- copyright: Catalyst IT Ltd, Morphoss Ltd <http://www.morphoss.com/>
- license: GNU LGPL version 3 or later

Includes
require ("Translation.php") (line 367)
Functions
awl_version (line 675)

Return the AWL version

void awl_version ()
check_by_regex (line 397)

Verify a value is OK by testing a regex against it. If it is an array apply it to each element in the array recursively. If it is an object we don't mess with it.

void check_by_regex ( $val, $regex)

- $val
- $regex

dbg_error_log (line 27)

Writes a debug message into the error log using printf syntax. If the first parameter is "ERROR" then the message will _always_ be logged.

Otherwise, the first parameter is a "component" name, and will only be logged if $c->dbg["component"] is set to some non-null value.

If you want to see every log message then $c->dbg["ALL"] can be set, to override the debugging status of the individual components.

- var: The component to identify itself, or "ERROR", or "LOG:component"

void dbg_error_log ()
dbg_log_array (line 151)

Function to dump an array to the error log, possibly recursively

- var: Which component should this log message identify itself from

void dbg_log_array ( $component, $name, $arr, [ $recursive = false])

- $component
- $name
- $arr
- $recursive

define_byte_mappings (line 498)
void define_byte_mappings ()
deprecated (line 623)
void deprecated ( $method)

- $method

fatal (line 58)
void fatal ()
force_utf8 (line 550)
void force_utf8 ( $input)

- $input

get_fields (line 477)

Get the names of the fields for a particular table

- return: of string The public fields in the table.

array get_fields (string $tablename)

- string $tablename: The name of the table.

gzdecode (line 639)
void gzdecode ( $instring)

- $instring

olson_from_tzstring (line 584)

Try and extract something like "Pacific/Auckland" or "America/Indiana/Indianapolis" if possible.

void olson_from_tzstring ( $tzstring)

- $tzstring

param_to_global (line 431)

Convert a parameter to a global. We first look in _POST and then in _GET, and if they passed in a bunch of valid characters, we will make sure the incoming is cleaned to only match that set.

void param_to_global (string $varname, string $match_regex, string $alias1, " 3)

- string $varname: The name of the global variable to put the answer in
- string $match_regex: The part of the parameter matching this regex will be returned
- string $alias1: An alias for the name that we should look for first.
- " 3: ... More aliases, in the order which they should be examined. $varname will be appended to the end.

quoted_printable_encode (line 385)

Process a string to fit the requirements of RFC2045 section 6.7. Note that this works, but replaces more characters than the minimum set. For readability the spaces aren't encoded as =20 though.

void quoted_printable_encode ( $string)

- $string

replace_uri_params (line 296)

Given a URL (presumably the current one) and a parameter, replace the value of parameter, extending the URL as necessary if the parameter is not already there.

- return: The URI with the replacements done.

string replace_uri_params (string $uri, array $replacements)

- string $uri: The URI we will be replacing parameters in.
- array $replacements: An array of replacement pairs array( "replace_this" => "with this" )

session_salted_md5 (line 194)

Make a salted MD5 string, given a string and (possibly) a salt.

If no salt is supplied we will generate a random one.

- return: The salt, a * and the MD5 of the salted string, as in SALT*SALTEDHASH

string session_salted_md5 (string $instr, [string $salt = &quot;&quot;])

- string $instr: The string to be salted and MD5'd
- string $salt: Some salt to sprinkle into the string to be MD5'd so we don't get the same PW always hashing to the same value.

session_salted_sha1 (line 218)

Make a salted SHA1 string, given a string and (possibly) a salt. PHP5 only (although it could be made to work on PHP4 (@see http://www.openldap.org/faq/data/cache/347.html). The algorithm used here is compatible with OpenLDAP so passwords generated through this function should be able to be migrated to OpenLDAP by using the part following the second '*', i.e.

the '{SSHA}....' part.

If no salt is supplied we will generate a random one.

- return: A *, the salt, a * and the SHA1 of the salted string, as in *SALT*SALTEDHASH

string session_salted_sha1 (string $instr, [string $salt = &quot;&quot;])

- string $instr: The string to be salted and SHA1'd
- string $salt: Some salt to sprinkle into the string to be SHA1'd so we don't get the same PW always hashing to the same value.

session_simple_md5 (line 175)

Make a plain MD5 hash of a string, identifying the type of hash it is

- return: The *MD5* and the MD5 of the string

string session_simple_md5 (string $instr)

- string $instr: The string to be salted and MD5'd

session_validate_password (line 234)

Checks what a user entered against the actual password on their account.

- return: Whether or not the users attempt matches what is already on file.

boolean session_validate_password (string $they_sent, string $we_have)

- string $they_sent: What the user entered.
- string $we_have: What we have in the database as their password. Which may (or may not) be a salted MD5.

trace_bug (line 93)

Not as sever as a fatal() call, but we want to log and trace it

void trace_bug ()
uuid (line 349)

Generates a Universally Unique IDentifier, version 4.

RFC 4122 (http://www.ietf.org/rfc/rfc4122.txt) defines a special type of Globally Unique IDentifiers (GUID), as well as several methods for producing them. One such method, described in section 4.4, is based on truly random or pseudo-random number generators, and is therefore implementable in a language like PHP.

We choose to produce pseudo-random numbers with the Mersenne Twister, and to always limit single generated numbers to 16 bits (ie. the decimal value 65535). That is because, even on 32-bit systems, PHP's RAND_MAX will often be the maximum *signed* value, with only the equivalent of 31 significant bits. Producing two 16-bit random numbers to make up a 32-bit one is less efficient, but guarantees that all 32 bits are random.

The algorithm for version 4 UUIDs (ie. those based on random number generators) states that all 128 bits separated into the various fields (32 bits, 16 bits, 16 bits, 8 bits and 8 bits, 48 bits) should be random, except : (a) the version number should be the last 4 bits in the 3rd field, and (b) bits 6 and 7 of the 4th field should be 01. We try to conform to that definition as efficiently as possible, generating smaller values where possible, and minimizing the number of base conversions.

- return: A UUID, made up of 32 hex digits and 4 hyphens.
- author: David Holmes <dholmes@cfdsoftware.net>
- copyright: Copyright (c) CFD Labs, 2006. This function may be used freely for any purpose ; it is distributed without any form of warranty whatsoever.

string uuid ()

Documentation generated on Wed, 04 Jul 2012 07:06:12 +0000 by phpDocumentor 1.4.3