3 * Utility functions of a general nature which are used by
4 * most AWL library classes.
7 * @subpackage Utilities
8 * @author Andrew McMillan <andrew@mcmillan.net.nz>
9 * @copyright Catalyst IT Ltd, Morphoss Ltd <http://www.morphoss.com/>
10 * @license http://gnu.org/copyleft/gpl.html GNU GPL v2 or later
13 if ( !function_exists('dbg_error_log') ) {
15 * Writes a debug message into the error log using printf syntax. If the first
16 * parameter is "ERROR" then the message will _always_ be logged.
17 * Otherwise, the first parameter is a "component" name, and will only be logged
18 * if $c->dbg["component"] is set to some non-null value.
20 * If you want to see every log message then $c->dbg["ALL"] can be set, to
21 * override the debugging status of the individual components.
23 * @var string $component The component to identify itself, or "ERROR", or "LOG:component"
24 * @var string $format A format string for the log message
25 * @var [string $parameter ...] Parameters for the format string.
27 function dbg_error_log() {
29 $args = func_get_args();
31 $component = array_shift($args);
32 if ( substr( $component, 0, 3) == "LOG" ) {
33 // Special escape case for stuff that always gets logged.
35 $component = substr($component,4);
37 else if ( $component == "ERROR" ) {
40 else if ( isset($c->dbg
["ALL"]) ) {
43 else if ( !isset($c->dbg
[strtolower($component)]) ) return;
45 $argc = func_num_args();
47 $format = array_shift($args);
52 @error_log
( $c->sysabbr
.": $type: $component:". vsprintf( $format, $args ) );
58 if ( !function_exists('apache_request_headers') ) {
60 * Compatibility so we can use the apache function name and still work with CGI
63 function apache_request_headers() {
65 function apache_request_headers() {
66 foreach($_SERVER as $key=>$value) {
67 if (substr($key,0,5)=="HTTP_") {
68 $key=str_replace(" ","-",ucwords(strtolower(str_replace("_"," ",substr($key,5)))));
80 if ( !function_exists('dbg_log_array') ) {
82 * Function to dump an array to the error log, possibly recursively
84 * @var string $component Which component should this log message identify itself from
85 * @var string $name What name should this array dump identify itself as
86 * @var array $arr The array to be dumped.
87 * @var boolean $recursive Should the dump recurse into arrays/objects in the array
89 function dbg_log_array( $component, $name, $arr, $recursive = false ) {
90 if ( !isset($arr) ||
(gettype($arr) != 'array' && gettype($arr) != 'object') ) {
91 dbg_error_log( $component, "%s: array is not set, or is not an array!", $name);
94 foreach ($arr as $key => $value) {
95 dbg_error_log( $component, "%s: >>%s<< = >>%s<<", $name, $key,
96 (gettype($value) == 'array' ||
gettype($value) == 'object' ?
gettype($value) : $value) );
97 if ( $recursive && (gettype($value) == 'array' ||
(gettype($value) == 'object' && "$key" != 'self' && "$key" != 'parent') ) ) {
98 dbg_log_array( $component, "$name"."[$key]", $value, $recursive );
106 if ( !function_exists("session_salted_md5") ) {
108 * Make a salted MD5 string, given a string and (possibly) a salt.
110 * If no salt is supplied we will generate a random one.
112 * @param string $instr The string to be salted and MD5'd
113 * @param 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.
114 * @return string The salt, a * and the MD5 of the salted string, as in SALT*SALTEDHASH
116 function session_salted_md5( $instr, $salt = "" ) {
117 if ( $salt == "" ) $salt = substr( md5(rand(100000,999999)), 2, 8);
118 dbg_error_log( "Login", "Making salted MD5: salt=$salt, instr=$instr, md5($salt$instr)=".md5($salt . $instr) );
119 return ( sprintf("*%s*%s", $salt, md5($salt . $instr) ) );
125 if ( !function_exists("session_salted_sha1") ) {
127 * Make a salted SHA1 string, given a string and (possibly) a salt. PHP5 only (although it
128 * could be made to work on PHP4 (@see http://www.openldap.org/faq/data/cache/347.html). The
129 * algorithm used here is compatible with OpenLDAP so passwords generated through this function
130 * should be able to be migrated to OpenLDAP by using the part following the second '*', i.e.
131 * the '{SSHA}....' part.
133 * If no salt is supplied we will generate a random one.
135 * @param string $instr The string to be salted and SHA1'd
136 * @param 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.
137 * @return string A *, the salt, a * and the SHA1 of the salted string, as in *SALT*SALTEDHASH
139 function session_salted_sha1( $instr, $salt = "" ) {
140 if ( $salt == "" ) $salt = substr( str_replace('*','',base64_encode(sha1(rand(100000,9999999),true))), 2, 9);
141 dbg_error_log( "Login", "Making salted SHA1: salt=$salt, instr=$instr, encoded($instr$salt)=".base64_encode(sha1($instr . $salt, true).$salt) );
142 return ( sprintf("*%s*{SSHA}%s", $salt, base64_encode(sha1($instr.$salt, true) . $salt ) ) );
147 if ( !function_exists("session_validate_password") ) {
149 * Checks what a user entered against the actual password on their account.
150 * @param string $they_sent What the user entered.
151 * @param string $we_have What we have in the database as their password. Which may (or may not) be a salted MD5.
152 * @return boolean Whether or not the users attempt matches what is already on file.
154 function session_validate_password( $they_sent, $we_have ) {
155 if ( preg_match('/^\*\*.+$/', $we_have ) ) {
156 // The "forced" style of "**plaintext" to allow easier admin setting
157 return ( "**$they_sent" == $we_have );
160 if ( preg_match('/^\*(.+)\*{[A-Z]+}.+$/', $we_have, $regs ) ) {
161 if ( function_exists("session_salted_sha1") ) {
162 // A nicely salted sha1sum like "*<salt>*{SSHA}<salted_sha1>"
164 $sha1_sent = session_salted_sha1( $they_sent, $salt ) ;
165 return ( $sha1_sent == $we_have );
168 dbg_error_log( "ERROR", "Password is salted SHA-1 but you are using PHP4!" );
172 <title>Salted SHA1 Password format not supported with PHP4</title>
175 <h1>Salted SHA1 Password format not supported with PHP4</h1>
176 <p>At some point you have used PHP5 to set the password for this user and now you are
177 using PHP4. You will need to assign a new password to this user using PHP4, or ensure
178 you use PHP5 everywhere (recommended).</p>
179 <p>AWL has now switched to using salted SHA-1 passwords by preference in a format
180 compatible with OpenLDAP.</p>
188 if ( preg_match('/^\*(.+)\*.+$/', $we_have, $regs ) ) {
189 // A nicely salted md5sum like "*<salt>*<salted_md5>"
191 $md5_sent = session_salted_md5( $they_sent, $salt ) ;
192 return ( $md5_sent == $we_have );
195 // Anything else is bad
203 if ( !function_exists("replace_uri_params") ) {
205 * Given a URL (presumably the current one) and a parameter, replace the value of parameter,
206 * extending the URL as necessary if the parameter is not already there.
207 * @param string $uri The URI we will be replacing parameters in.
208 * @param array $replacements An array of replacement pairs array( "replace_this" => "with this" )
209 * @return string The URI with the replacements done.
211 function replace_uri_params( $uri, $replacements ) {
213 foreach( $replacements AS $param => $new_value ) {
214 $rxp = preg_replace( '/([\[\]])/', '\\\\$1', $param ); // Some parameters may be arrays.
215 $regex = "/([&?])($rxp)=([^&]+)/";
216 dbg_error_log("core", "Looking for [%s] to replace with [%s] regex is %s and searching [%s]", $param, $new_value, $regex, $replaced );
217 if ( preg_match( $regex, $replaced ) )
218 $replaced = preg_replace( $regex, "\$1$param=$new_value", $replaced);
220 $replaced .= "&$param=$new_value";
222 if ( ! preg_match( '/\?/', $replaced ) ) {
223 $replaced = preg_replace("/&(.+)$/", "?\$1", $replaced);
225 $replaced = str_replace("&", "--AmPeRsAnD--", $replaced);
226 $replaced = str_replace("&", "&", $replaced);
227 $replaced = str_replace("--AmPeRsAnD--", "&", $replaced);
228 dbg_error_log("core", "URI <<$uri>> morphed to <<$replaced>>");
234 if ( !function_exists("uuid") ) {
236 * Generates a Universally Unique IDentifier, version 4.
238 * RFC 4122 (http://www.ietf.org/rfc/rfc4122.txt) defines a special type of Globally
239 * Unique IDentifiers (GUID), as well as several methods for producing them. One
240 * such method, described in section 4.4, is based on truly random or pseudo-random
241 * number generators, and is therefore implementable in a language like PHP.
243 * We choose to produce pseudo-random numbers with the Mersenne Twister, and to always
244 * limit single generated numbers to 16 bits (ie. the decimal value 65535). That is
245 * because, even on 32-bit systems, PHP's RAND_MAX will often be the maximum *signed*
246 * value, with only the equivalent of 31 significant bits. Producing two 16-bit random
247 * numbers to make up a 32-bit one is less efficient, but guarantees that all 32 bits
250 * The algorithm for version 4 UUIDs (ie. those based on random number generators)
251 * states that all 128 bits separated into the various fields (32 bits, 16 bits, 16 bits,
252 * 8 bits and 8 bits, 48 bits) should be random, except : (a) the version number should
253 * be the last 4 bits in the 3rd field, and (b) bits 6 and 7 of the 4th field should
254 * be 01. We try to conform to that definition as efficiently as possible, generating
255 * smaller values where possible, and minimizing the number of base conversions.
257 * @copyright Copyright (c) CFD Labs, 2006. This function may be used freely for
258 * any purpose ; it is distributed without any form of warranty whatsoever.
259 * @author David Holmes <dholmes@cfdsoftware.net>
261 * @return string A UUID, made up of 32 hex digits and 4 hyphens.
266 // The field names refer to RFC 4122 section 4.1.2
268 return sprintf('%04x%04x-%04x-%03x4-%04x-%04x%04x%04x',
269 mt_rand(0, 65535), mt_rand(0, 65535), // 32 bits for "time_low"
270 mt_rand(0, 65535), // 16 bits for "time_mid"
271 mt_rand(0, 4095), // 12 bits before the 0100 of (version) 4 for "time_hi_and_version"
272 bindec(substr_replace(sprintf('%016b', mt_rand(0, 65535)), '01', 6, 2)),
273 // 8 bits, the last two of which (positions 6 and 7) are 01, for "clk_seq_hi_res"
274 // (hence, the 2nd hex digit after the 3rd hyphen can only be 1, 5, 9 or d)
275 // 8 bits for "clk_seq_low"
276 mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535) // 48 bits for "node"
281 if ( !function_exists("translate") ) {
282 require("Translation.php");
285 if ( !function_exists("clone") && version_compare(phpversion(), '5.0') < 0) {
287 * PHP5 screws with the assignment operator changing so that $a = $b means that
288 * $a becomes a reference to $b. There is a clone() that we can use in PHP5, so
289 * we have to emulate that for PHP4. Bleargh.
291 eval( 'function clone($object) { return $object; }' );
294 if ( !function_exists("quoted_printable_encode") ) {
296 * Process a string to fit the requirements of RFC2045 section 6.7. Note that
297 * this works, but replaces more characters than the minimum set. For readability
298 * the spaces aren't encoded as =20 though.
300 function quoted_printable_encode($string) {
301 return preg_replace('/[^\r\n]{73}[^=\r\n]{2}/', "$0=\r\n", str_replace("%","=",str_replace("%20"," ",rawurlencode($string))));
306 if ( !function_exists("clean_by_regex") ) {
308 * Clean a value by applying a regex to it. If it is an array apply it to
309 * each element in the array recursively. If it is an object we don't mess
312 function clean_by_regex( $val, $regex ) {
313 if ( is_null($val) ) return null;
315 case 'int': $regex = '#^\d+$#'; break;
317 if ( is_array($val) ) {
318 foreach( $val AS $k => $v ) {
319 $val[$k] = clean_by_regex($v,$regex);
322 else if ( ! is_object($val) ) {
323 if ( preg_match( $regex, $val, $matches) ) {
335 if ( !function_exists("param_to_global") ) {
337 * Convert a parameter to a global. We first look in _POST and then in _GET,
338 * and if they passed in a bunch of valid characters, we will make sure the
339 * incoming is cleaned to only match that set.
341 * @param string $varname The name of the global variable to put the answer in
342 * @param string $match_regex The part of the parameter matching this regex will be returned
343 * @param string $alias1 An alias for the name that we should look for first.
344 * @param " ... More aliases, in the order which they should be examined. $varname will be appended to the end.
346 function param_to_global( ) {
347 $args = func_get_args();
349 $varname = array_shift($args);
350 $GLOBALS[$varname] = null;
353 $argc = func_num_args();
355 $match_regex = array_shift($args);
359 foreach( $args AS $k => $name ) {
360 if ( isset($_POST[$name]) ) {
361 $result = $_POST[$name];
364 else if ( isset($_GET[$name]) ) {
365 $result = $_GET[$name];
369 if ( !isset($result) ) return null;
371 if ( isset($match_regex) ) {
372 $result = clean_by_regex( $result, $match_regex );
375 $GLOBALS[$varname] = $result;
381 if ( !function_exists("get_fields") ) {
383 * @var array $_AWL_field_cache is a cache of the field names for a table
385 $_AWL_field_cache = array();
389 * Get the names of the fields for a particular table
390 * @param string $tablename The name of the table.
391 * @return array of string The public fields in the table.
393 function get_fields( $tablename ) {
394 global $_AWL_field_cache;
396 if ( !isset($_AWL_field_cache[$tablename]) ) {
397 dbg_error_log( "DataUpdate", ":get_fields: Loaded fields for table '$tablename'" );
398 $sql = "SELECT f.attname, t.typname, f.atttypmod FROM pg_attribute f ";
399 $sql .= "JOIN pg_class c ON ( f.attrelid = c.oid ) ";
400 $sql .= "JOIN pg_type t ON ( f.atttypid = t.oid ) ";
401 $sql .= "WHERE relname = ? AND attnum >= 0 order by f.attnum;";
402 $qry = new PgQuery( $sql, $tablename );
403 $qry->Exec("DataUpdate");
405 while( $row = $qry->Fetch() ) {
406 $fields["$row->attname"] = $row->typname
. ($row->atttypmod
!= -1 ?
sprintf('(%d)',$row->atttypmod
) : '');
408 $_AWL_field_cache[$tablename] = $fields;
410 return $_AWL_field_cache[$tablename];
415 if ( !function_exists("force_utf8") ) {
416 function define_byte_mappings() {
417 global $byte_map, $nibble_good_chars;
419 # Needed for using Grant McLean's byte mappings code
420 $ascii_char = '[\x00-\x7F]';
421 $cont_byte = '[\x80-\xBF]';
423 $utf8_2 = '[\xC0-\xDF]' . $cont_byte;
424 $utf8_3 = '[\xE0-\xEF]' . $cont_byte . '{2}';
425 $utf8_4 = '[\xF0-\xF7]' . $cont_byte . '{3}';
426 $utf8_5 = '[\xF8-\xFB]' . $cont_byte . '{4}';
428 $nibble_good_chars = "/^($ascii_char+|$utf8_2|$utf8_3|$utf8_4|$utf8_5)(.*)$/s";
430 # From http://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/CP1252.TXT
432 "\x80" => "\xE2\x82\xAC", # EURO SIGN
433 "\x82" => "\xE2\x80\x9A", # SINGLE LOW-9 QUOTATION MARK
434 "\x83" => "\xC6\x92", # LATIN SMALL LETTER F WITH HOOK
435 "\x84" => "\xE2\x80\x9E", # DOUBLE LOW-9 QUOTATION MARK
436 "\x85" => "\xE2\x80\xA6", # HORIZONTAL ELLIPSIS
437 "\x86" => "\xE2\x80\xA0", # DAGGER
438 "\x87" => "\xE2\x80\xA1", # DOUBLE DAGGER
439 "\x88" => "\xCB\x86", # MODIFIER LETTER CIRCUMFLEX ACCENT
440 "\x89" => "\xE2\x80\xB0", # PER MILLE SIGN
441 "\x8A" => "\xC5\xA0", # LATIN CAPITAL LETTER S WITH CARON
442 "\x8B" => "\xE2\x80\xB9", # SINGLE LEFT-POINTING ANGLE QUOTATION MARK
443 "\x8C" => "\xC5\x92", # LATIN CAPITAL LIGATURE OE
444 "\x8E" => "\xC5\xBD", # LATIN CAPITAL LETTER Z WITH CARON
445 "\x91" => "\xE2\x80\x98", # LEFT SINGLE QUOTATION MARK
446 "\x92" => "\xE2\x80\x99", # RIGHT SINGLE QUOTATION MARK
447 "\x93" => "\xE2\x80\x9C", # LEFT DOUBLE QUOTATION MARK
448 "\x94" => "\xE2\x80\x9D", # RIGHT DOUBLE QUOTATION MARK
449 "\x95" => "\xE2\x80\xA2", # BULLET
450 "\x96" => "\xE2\x80\x93", # EN DASH
451 "\x97" => "\xE2\x80\x94", # EM DASH
452 "\x98" => "\xCB\x9C", # SMALL TILDE
453 "\x99" => "\xE2\x84\xA2", # TRADE MARK SIGN
454 "\x9A" => "\xC5\xA1", # LATIN SMALL LETTER S WITH CARON
455 "\x9B" => "\xE2\x80\xBA", # SINGLE RIGHT-POINTING ANGLE QUOTATION MARK
456 "\x9C" => "\xC5\x93", # LATIN SMALL LIGATURE OE
457 "\x9E" => "\xC5\xBE", # LATIN SMALL LETTER Z WITH CARON
458 "\x9F" => "\xC5\xB8", # LATIN CAPITAL LETTER Y WITH DIAERESIS
461 for( $i=160; $i < 256; $i++
) {
463 $byte_map[$ch] = iconv('ISO-8859-1', 'UTF-8', $ch);
466 define_byte_mappings();
468 function force_utf8( $input ) {
472 while( $input != '' ) {
473 if ( preg_match( $nibble_good_chars, $input, $matches ) ) {
474 $output .= $matches[1];
478 preg_match( '/^(.)(.*)$/s', $input, $matches );
481 if ( isset($byte_map[$char]) ) {
482 $output .= $byte_map[$char];
485 # Must be valid UTF8 already