source: branches/1.1dev/lib/Utilities.inc.php @ 569

<?php
/**
 * Utilities.inc.php
 * Code by Strangecode :: www.strangecode.com :: This document contains copyrighted information
 */


/**
 * Print variable dump.
 *
 * @param  mixed $var      Variable to dump.
 * @param  bool  $display   Hide the dump in HTML comments?
 * @param  bool  $var_dump Use var_dump instead of print_r.
 */
function dump($var, $display=false, $var_dump=false)
{
    echo $display ? "\n<br /><pre>\n" : "\n\n\n<!--\n";
    if ($var_dump) {
        var_dump($var);
    } else {
        print_r($var);
    }
    echo $display ?  "\n</pre><br />\n" : "\n-->\n\n\n";
}

/**
 * Return dump as variable.
 *
 * @param  mixed $var      Variable to dump.
 *
 * @return string Dump of var.
 */
function getDump($var)
{
    ob_start();
    print_r($var);
    $d = ob_get_contents();
    ob_end_clean();
    return $d;
}

/**
 * Return dump as cleaned text. Useful for dumping data into emails.
 *
 * @param  mixed $var      Variable to dump.
 *
 * @return string Dump of var.
 */
function fancyDump($var, $indent='')
{
    $output = '';
    if (is_array($var)) {
        foreach ($var as $k=>$v) {
            $k = ucfirst(strtolower(str_replace(array('_', '  '), ' ', $k)));
            if (is_array($v)) {
                $output .= sprintf("\n%s%s: %s\n", $indent, $k, fancyDump($v, $indent . $indent));
            } else {
                $output .= sprintf("%s%s: %s\n", $indent, $k, $v);
            }
        }
    } else {
        $output .= sprintf("%s%s\n", $indent, $var);
    }
    return $output;
}

/**
 * Returns text with appropriate html translations. 
 *
 * @param  string $txt              Text to clean.
 * @param  bool   $preserve_html    If set to true, oTxt will not translage <, >, ", or ' 
 *                                  characters into HTML entities. This allows HTML to pass
 *                                  through unmunged.
 *
 * @return string                   Cleaned text.
 */
function oTxt($txt, $preserve_html=false)
{
    global $CFG;

    $search = array();
    $replace = array();

    // Make converted ampersand entities into normal ampersands (they will be done manually later) to retain HTML entities.
    $search['retain_ampersand']     = '/&amp;/';
    $replace['retain_ampersand']    = '&';

    if ($preserve_html) {
        // Convert characters that must remain non-entities for displaying HTML.
        $search['retain_left_angle']       = '/&lt;/';
        $replace['retain_left_angle']      = '<';
        
        $search['retain_right_angle']      = '/&gt;/';
        $replace['retain_right_angle']     = '>';
        
        $search['retain_single_quote']     = '/&#039;/';
        $replace['retain_single_quote']    = "'";
        
        $search['retain_double_quote']     = '/&quot;/';
        $replace['retain_double_quote']    = '"';
    }

    // & becomes &amp;
    $search['ampersand']        = '/&((?![\w\d#]{1,10};))/';
    $replace['ampersand']       = '&amp;\\1';

    return preg_replace($search, $replace, htmlentities($txt, ENT_QUOTES, $CFG->character_set));
}

/**
 * Returns text with stylistic modifications. 
 *
 * @param  string   $txt  Text to clean.
 *
 * @return string         Cleaned text.
 */
function fancyTxt($txt)
{
    $search = array();
    $replace = array();

    // "double quoted text"  becomes  &ldquo;double quoted text&rdquo;
    $search['double_quotes']    = '/(^|[^\w=])(?:"|&quot;|&#34;|&#x22;|&ldquo;)([^"]+?)(?:"|&quot;|&#34;|&#x22;|&rdquo;)([^\w]|$)/'; // " is the same as &quot; and &#34; and &#x22;
    $replace['double_quotes']   = '\\1&ldquo;\\2&rdquo;\\3';

    // text's apostrophes  become  text&rsquo;s apostrophes
    $search['apostrophe']       = '/(\w)(?:\'|&#39;)(\w)/';
    $replace['apostrophe']      = '\\1&rsquo;\\2';

    // "single quoted text"  becomes  &lsquo;single quoted text&rsquo;
    $search['single_quotes']    = '/(^|[^\w=])(?:\'|&#39;|&lsquo;)([^\']+?)(?:\'|&#39;|&rsquo;)([^\w]|$)/';
    $replace['single_quotes']   = '\\1&lsquo;\\2&rsquo;\\3';
    
    // em--dashes  become em&mdash;dashes
    $search['em_dash']          = '/(\s*[^!<-])--([^>-]\s*)/';
    $replace['em_dash']         = '\\1&mdash;\\2';
    
    // & becomes &amp;
    $search['ampersand']        = '/&((?![\w\d#]{1,10};))/';
    $replace['ampersand']       = '&amp;\\1';

    return preg_replace($search, $replace, $txt);
}

/**
 * Turns "a really long string" into "a rea...string"
 *
 * @access  public
 * @param   string  $str    Input string
 * @param   int     $len    Maximum string length.
 * @param   string  $where  Where to cut the string. One of: 'start', 'middle', or 'end'.
 * @return  string          Truncated output string
 * @author  Quinn Comendant <quinn@strangecode.com>
 * @since   29 Mar 2006 13:48:49
 */
function truncate($str, $len, $where='end', $delim='
')
{
    if ($len <= 3 || mb_strlen($str) <= 3) {
        return '';
    }
    $part1 = floor(($len - 3) / 2);
    $part2 = ceil(($len - 3) / 2);
    switch ($where) {
    case 'start' :
        return preg_replace(array(sprintf('/^.{4,}(.{%s})$/sU', $part1 + $part2), '/\s*\.{3,}\s*/sU'), array($delim . '$1', $delim), $str);
        break;
    default :
    case 'middle' :
        return preg_replace(array(sprintf('/^(.{%s}).{4,}(.{%s})$/sU', $part1, $part2), '/\s*\.{3,}\s*/sU'), array('$1' . $delim . '$2', $delim), $str);
        break;    
    case 'end' :
        return preg_replace(array(sprintf('/^(.{%s}).{4,}$/sU', $part1 + $part2), '/\s*\.{3,}\s*/sU'), array('$1' . $delim, $delim), $str);
        break;
    }
}
    
/**
 * Generates a hexadecimal html color based on provided word.
 *
 * @access public
 *
 * @param  string $text  A string for which to convert to color.
 *
 * @return string  A hexadecimal html color.
 */
function getTextColor($text, $method=1)
{
    $hash = md5($text);
    $rgb = array(
        substr($hash, 0, 1),
        substr($hash, 1, 1),
        substr($hash, 2, 1),
        substr($hash, 3, 1),
        substr($hash, 4, 1),
        substr($hash, 5, 1),
    );

    switch ($method) {
    case 1 :
    default :
        // Reduce all hex values slighly to avoid all white.
        array_walk($rgb, create_function('&$v', '$v = dechex(round(hexdec($v) * 0.87));'));
        break;
    case 2 :
        foreach ($rgb as $i => $v) {
            if (hexdec($v) > hexdec('c')) {
                $rgb[$i] = dechex(hexdec('f') - hexdec($v));
            }
        }
        break;
    }

    return join('', $rgb);
}

/**
 * Encodes a string into unicode values 128-255.
 * Useful for hiding an email address from spambots.
 *
 * @access  public
 *
 * @param   string   $text   A line of text to encode.
 *
 * @return  string   Encoded text.
 */
function encodeAscii($text)
{
    $ouput = '';
    $num = strlen($text);
    for ($i=0; $i<$num; $i++) {
        $output .= sprintf('&#%03s', ord($text{$i}));
    }
    return $output;
}

/**
 * Encodes an email into a user (at) domain (dot) com format.
 *
 * @access  public
 * @param   string   $email   An email to encode.
 * @param   string   $at      Replaces the @.
 * @param   string   $dot     Replaces the ..
 * @return  string   Encoded email.
 */
function encodeEmail($email, $at=' at ', $dot=' dot ')
{
    $search = array('/@/', '/\./');
    $replace = array($at, $dot);
    return preg_replace($search, $replace, $email);
}

/**
 * Return a human readable filesize.
 *
 * @param       int    $size        Size
 * @param       int    $unit        The maximum unit
 * @param       int    $format      The return string format
 * @author      Aidan Lister <aidan@php.net>
 * @version     1.1.0
 */
function humanFileSize($size, $unit=null, $format='%01.2f %s')
{
    // Units
    $units = array('B', 'KB', 'MB', 'GB', 'TB');
    $ii = count($units) - 1;
  
    // Max unit
    $unit = array_search((string) $unit, $units);
    if ($unit === null || $unit === false) {
        $unit = $ii;
    }
  
    // Loop
    $i = 0;
    while ($unit != $i && $size >= 1024 && $i < $ii) {
        $size /= 1024;
        $i++;
    }
  
    return sprintf($format, $size, $units[$i]);
}

/**
 * If $var is net set or null, set it to $default. Otherwise leave it alone.
 * Returns the final value of $var. Use to find a default value of one is not avilable.
 *
 * @param  mixed $var       The variable that is being set.
 * @param  mixed $default   What to set it to if $val is not currently set.
 * @return mixed            The resulting value of $var. 
 */
function setDefault(&$var, $default='')
{
    if (!isset($var)) {
        $var = $default;
    }
    return $var;
}

/**
 * Like preg_quote() except for arrays, it takes an array of strings and puts
 * a backslash in front of every character that is part of the regular
 * expression syntax.
 *
 * @param  array $array    input array
 * @param  array $delim    optional character that will also be excaped.
 *
 * @return array    an array with the same values as $array1 but shuffled
 */
function pregQuoteArray($array, $delim='/')
{
    if (!empty($array)) {
        if (is_array($array)) {
            foreach ($array as $key=>$val) {
                $quoted_array[$key] = preg_quote($val, $delim);
            }
            return $quoted_array;
        } else {
            return preg_quote($array, $delim);
        }
    }
}

/**
 * Converts a PHP Array into encoded URL arguments and return them as an array.
 *
 * @param  mixed $data        An array to transverse recursively, or a string
 *                            to use directly to create url arguments.
 * @param  string $prefix     The name of the first dimension of the array.
 *                            If not specified, the first keys of the array will be used.
 *
 * @return array              URL with array elements as URL key=value arguments.
 */
function urlEncodeArray($data, $prefix='', $_return=true) {
   
    // Data is stored in static variable.
    static $args;
    
    if (is_array($data)) {
        foreach ($data as $key => $val) {
            // If the prefix is empty, use the $key as the name of the first dimension of the "array".
            // ...otherwise, append the key as a new dimension of the "array".
            $new_prefix = ('' == $prefix) ? urlencode($key) : $prefix . '[' . urlencode($key) . ']';
            // Enter recursion.
            urlEncodeArray($val, $new_prefix, false);
        }
    } else {
        // We've come to the last dimension of the array, save the "array" and it's value.
        $args[$prefix] = urlencode($data);
    }
    
    if ($_return) {
        // This is not a recursive execution. All recursion is complete.
        // Reset static var and return the result.
        $ret = $args;
        $args = array();
        return is_array($ret) ? $ret : array();
    }
}

/**
 * Converts a PHP Array into encoded URL arguments and return them in a string.
 *
 * @param  mixed $data        An array to transverse recursively, or a string
 *                            to use directly to create url arguments.
 * @param  string $prefix     The name of the first dimension of the array.
 *                            If not specified, the first keys of the array will be used.
 *
 * @return string url         A string ready to append to a url.
 */
function urlEncodeArrayToString($data, $prefix='') {
    
    $array_args = urlEncodeArray($data, $prefix);
    $url_args = '';
    $delim = '';
    foreach ($array_args as $key=>$val) {
        $url_args .= $delim . $key . '=' . $val;
        $delim = ini_get('arg_separator.output');
    }
    return $url_args;
}

/**
 * An alternative to "shuffle()" that actually works. 
 *
 * @param  array $array1   input array
 * @param  array $array2   argument used internally through recursion
 *
 * @return array    an array with the same values as $array1 but shuffled
 */
function arrayRand(&$array1, $array2 = array())
{
    if (!sizeof($array1)) {
        return array();
    }
    
    srand((double) microtime() * 10000000);
    $rand = array_rand($array1);
    
    $array2[] = $array1[$rand];
    unset ($array1[$rand]);
    
    return $array2 + arrayRand($array1, $array2);
}

/**
 * Fills an arrray with the result from a multiple ereg search.
 * Curtesy of Bruno - rbronosky@mac.com - 10-May-2001
 * Blame him for the funky do...while loop.
 *
 * @param  mixed $pattern   regular expression needle
 * @param  mixed $string   haystack
 *
 * @return array    populated with each found result
 */
function eregAll($pattern, $string)
{
    do {
        if (!ereg($pattern, $string, $temp)) {
             continue;
        }
        $string = str_replace($temp[0], '', $string);
        $results[] = $temp;
    } while (ereg($pattern, $string, $temp));
    return $results;
}

/**
 * Prints the word "checked" if a variable is set, and optionally matches
 * the desired value, otherwise prints nothing,
 * used for printing the word "checked" in a checkbox form input. 
 *
 * @param  mixed $var     the variable to compare
 * @param  mixed $value   optional, what to compare with if a specific value is required.
 */
function frmChecked($var, $value=null)
{
    if (func_num_args() == 1 && $var) {
        // 'Checked' if var is true.
        echo ' checked="checked" ';
    } else if (func_num_args() == 2 && $var == $value) {
        // 'Checked' if var and value match.
        echo ' checked="checked" ';
    } else if (func_num_args() == 2 && is_array($var)) {
        // 'Checked' if the value is in the key or the value of an array.
        if (isset($var[$value])) {
            echo ' checked="checked" ';
        } else if (in_array($value, $var)) {
            echo ' checked="checked" ';
        }
    }
}

/**
 * prints the word "selected" if a variable is set, and optionally matches
 * the desired value, otherwise prints nothing,
 * otherwise prints nothing, used for printing the word "checked" in a 
 * select form input 
 *
 * @param  mixed $var     the variable to compare
 * @param  mixed $value   optional, what to compare with if a specific value is required.
 */
function frmSelected($var, $value=null)
{
    if (func_num_args() == 1 && $var) {
        // 'selected' if var is true.
        echo ' selected="selected" ';
    } else if (func_num_args() == 2 && $var == $value) {
        // 'selected' if var and value match.
        echo ' selected="selected" ';
    } else if (func_num_args() == 2 && is_array($var)) {
        // 'selected' if the value is in the key or the value of an array.
        if (isset($var[$value])) {
            echo ' selected="selected" ';
        } else if (in_array($value, $var)) {
            echo ' selected="selected" ';
        }
    }
}

/**
 * Adds slashes to values of an array and converts the array to a
 * comma delimited list. If value provided is not an array or is empty
 * return nothing. This is useful for putting values coming in from
 * posted checkboxes into a SET column of a database.
 *
 * @param  array $array   Array to convert.
 * @return string         Comma list of array values.
 */
function dbArrayToList($array)
{
    if (is_array($array) && !empty($array)) {
        return join(',', array_map('mysql_real_escape_string', array_keys($array)));
    }
}

/**
 * Converts a human string date into a SQL-safe date.
 * Dates nearing infinity use the date 2038-01-01 so conversion to unix time
 * format remain within valid range.
 *
 * @param  array $date     String date to convert.
 * @param  array $format   Date format to pass to date(). 
 *                         Default produces MySQL datetime: 0000-00-00 00:00:00.
 *
 * @return string          SQL-safe date.
 */
function strToSQLDate($date, $format='Y-m-d H:i:s')
{
    // Translate the human string date into SQL-safe date format.
    if (empty($date) || '0000-00-00' == $date || strtotime($date) === -1) {
        $sql_date = '0000-00-00';
    } else {
        $sql_date = date($format, strtotime($date));
    }
    
    return $sql_date;
}

/**
 * If magic_quotes_gpc is in use, run stripslashes() on $var. If $var is an
 * array, stripslashes is run on each value, recursively, and the stripped
 * array is returned
 *
 * @param  mixed $var   The string or array to un-quote, if necessary.
 * @return mixed        $var, minus any magic quotes.
 */
function dispelMagicQuotes($var)
{
    static $magic_quotes_gpc;
    
    if (!isset($magic_quotes_gpc)) {
        $magic_quotes_gpc = get_magic_quotes_gpc();
    }
    
    if ($magic_quotes_gpc) {
        if (!is_array($var)) {
            $var = stripslashes($var);
        } else {
            foreach ($var as $key=>$val) {
                if (is_array($val)) {
                    $var[$key] = dispelMagicQuotes($val);
                } else {
                    $var[$key] = stripslashes($val);
                }
            }
        }
    }
    return $var;
}

/**
 * Get a form variable from GET or POST data, stripped of magic
 * quotes if necessary.
 *
 * @param string $var (optional) The name of the form variable to look for.
 * @param string $default (optional) The value to return if the
 *                                   variable is not there.
 *
 * @return mixed      A cleaned GET or POST if no $var specified.
 * @return string     A cleaned form $var if found, or $default.
 */
function getFormData($var=null, $default=null)
{
    if ('POST' == $_SERVER['REQUEST_METHOD'] && is_null($var)) {
        return dispelMagicQuotes($_POST);
    } else if ('GET' == $_SERVER['REQUEST_METHOD'] && is_null($var)) {
        return dispelMagicQuotes($_GET);
    }
    if (isset($_POST[$var])) {
        return dispelMagicQuotes($_POST[$var]);
    } else if (isset($_GET[$var])) {
        return dispelMagicQuotes($_GET[$var]);
    } else {
        return $default;
    }
}
function getPost($var=null, $default=null)
{
    if (is_null($var)) {
        return dispelMagicQuotes($_POST);
    }
    if (isset($_POST[$var])) {
        return dispelMagicQuotes($_POST[$var]);
    } else {
        return $default;
    }
}
function getGet($var=null, $default=null)
{
    if (is_null($var)) {
        return dispelMagicQuotes($_GET);
    }
    if (isset($_GET[$var])) {
        return dispelMagicQuotes($_GET[$var]);
    } else {
        return $default;
    }
}

/**
 * Signs a value using md5 and a simple text key. In order for this
 * function to be useful (i.e. secure) the key must be kept secret, which
 * means keeping it as safe as database credentials. Putting it into an
 * environment variable set in httpd.conf is a good place.
 *
 * @access  public
 *
 * @param   string  $val    The string to sign.
 * @param   string  $key    (Optional) A text key to use for computing the signature.
 *
 * @return  string  The original value with a signature appended.
 */
function addSignature($val, $key=null)
{
    global $CFG;
    
    if ('' == $val) {
        logMsg(sprintf('Adding signature to empty string.', null), LOG_NOTICE, __FILE__, __LINE__);
    }
    
    if (!isset($key)) {
        $key = $CFG->signing_key;
    }

    return $val . '-' . substr(md5($val . $key), 0, 18);
}

/**
 * Strips off the signature appended by addSignature().
 *
 * @access  public
 *
 * @param   string  $signed_val     The string to sign.
 *
 * @return  string  The original value with a signature removed.
 */
function removeSignature($signed_val)
{
    return substr($signed_val, 0, strrpos($signed_val, '-'));
}


/**
 * Verifies a signature appened to a value by addSignature().
 *
 * @access  public
 *
 * @param   string  $signed_val A value with appended signature.
 * @param   string  $key        (Optional) A text key to use for computing the signature.
 *
 * @return  bool    True if the signature matches the var.
 */
function verifySignature($signed_val, $key=null)
{
    // Strip the value from the signed value.
    $val = substr($signed_val, 0, strrpos($signed_val, '-'));
    // If the signed value matches the original signed value we consider the value safe.
    if ($signed_val == addSignature($val, $key)) {
        // Signature verified.
        return true;
    } else {
        return false;
    }
}

/**
 * Stub functions used when installation does not have
 * GNU gettext extension installed
 */
if (!extension_loaded('gettext')) {
    /**
    * Translates text
    * 
    * @access public
    * @param string $text the text to be translated
    * @return string translated text
    */
    function gettext($text) {
        return $text;
    }
    
    /**
    * Translates text
    * 
    * @access public
    * @param string $text the text to be translated
    * @return string translated text
    */
    function _($text) {
        return $text;
    }
    
    /**
    * Translates text by domain
    * 
    * @access public
    * @param string $domain the language to translate the text into
    * @param string $text the text to be translated
    * @return string translated text
    */
    function dgettext($domain, $text) {
        return $text;
    }
    
    /**
    * Translates text by domain and category
    * 
    * @access public
    * @param string $domain the language to translate the text into
    * @param string $text the text to be translated
    * @param string $category the language dialect to use
    * @return string translated text
    */
    function dcgettext($domain, $text, $category) {
        return $text;
    }
    
    /**
    * Binds the text domain
    * 
    * @access public
    * @param string $domain the language to translate the text into
    * @param string 
    * @return string translated text
    */
    function bindtextdomain($domain, $directory) {
        return $domain;
    }
    
    /**
    * Sets the text domain
    * 
    * @access public
    * @param string $domain the language to translate the text into
    * @return string translated text
    */
    function textdomain($domain) {
        return $domain;
    }
}

/**
 * Sends empty output to the browser and flushes the php buffer so the client
 * will see data before the page is finished processing. 
 */
function flushBuffer() {
    echo str_repeat('          ', 205);
    flush();
}

/**
 * Adds email address to mailman mailing list. Requires /etc/sudoers entry for apache to sudo execute add_members.
 * Don't forget to allow php_admin_value open_basedir access to "/var/mailman/bin".
 *
 * @access  public
 *
 * @param   string  $email     Email address to add.
 * @param   string  $list      Name of list to add to.
 * @param   bool    $send_welcome_message   True to send welcome message to subscriber.
 *
 * @return  bool    True on success, false on failure.
 */
function mailmanAddMember($email, $list, $send_welcome_message=false)
{
   $add_members = '/usr/lib/mailman/bin/add_members';
    if (true || is_executable($add_members) && is_readable($add_members)) {
        $welcome_msg = $send_welcome_message ? 'y' : 'n';
        exec(sprintf('/bin/echo %s | /usr/bin/sudo %s -r - --welcome-msg=%s --admin-notify=n %s', escapeshellarg($email), escapeshellarg($add_members), $welcome_msg, escapeshellarg($list)), $stdout, $return_code);
        $stdout = is_array($stdout) ? getDump($stdout) : $stdout;
        if (0 == $return_code) {
            logMsg(sprintf('Mailman add member success for list: %s, user: %s', $list, $email, $stdout), LOG_INFO, __FILE__, __LINE__);
            return true;
        } else {
            logMsg(sprintf('Mailman add member failed for list: %s, user: %s, with message: %s', $list, $email, $stdout), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }
    } else {
        logMsg(sprintf('Mailman add member program not executable: %s', $add_members), LOG_ALERT, __FILE__, __LINE__);
        return false;
    }
}

/**
 * Removes email address from mailman mailing list. Requires /etc/sudoers entry for apache to sudo execute add_members.
 * Don't forget to allow php_admin_value open_basedir access to "/var/mailman/bin".
 *
 * @access  public
 *
 * @param   string  $email     Email address to add.
 * @param   string  $list      Name of list to add to.
 * @param   bool    $send_user_ack   True to send goodbye message to subscriber.
 *
 * @return  bool    True on success, false on failure.
 */
function mailmanRemoveMember($email, $list, $send_user_ack=false)
{
    $remove_members = '/usr/lib/mailman/bin/remove_members';
    if (true || is_executable($remove_members) && is_readable($remove_members)) {
        $userack = $send_user_ack ? '' : '--nouserack';
        exec(sprintf('/usr/bin/sudo %s %s --noadminack %s %s', escapeshellarg($remove_members), $userack, escapeshellarg($list), escapeshellarg($email)), $stdout, $return_code);
        $stdout = is_array($stdout) ? getDump($stdout) : $stdout;
        if (0 == $return_code) {
            logMsg(sprintf('Mailman remove member success for list: %s, user: %s', $list, $email, $stdout), LOG_INFO, __FILE__, __LINE__);
            return true;
        } else {
            logMsg(sprintf('Mailman remove member failed for list: %s, user: %s, with message: %s', $list, $email, $stdout), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }
    } else {
        logMsg(sprintf('Mailman remove member program not executable: %s', $remove_members), LOG_ALERT, __FILE__, __LINE__);
        return false;
    }
}



?>