X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=CRM%2FUtils%2FString.php;h=b561cad091520ce2d7915a0d803cabe34aff5ade;hb=f6d1d432c84df22d11d6a397a50b66939f0e7f43;hp=e703b2ae2be5b30b3ddb9c97ccca13eb13169d90;hpb=fa92b4af1c4abf280689cea6445c7a9b99858831;p=civicrm-core.git

diff --git a/CRM/Utils/String.php b/CRM/Utils/String.php
index e703b2ae2b..b561cad091 100644
--- a/CRM/Utils/String.php
+++ b/CRM/Utils/String.php
@@ -23,20 +23,19 @@
  | GNU Affero General Public License or the licensing of CiviCRM,     |
  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  +--------------------------------------------------------------------+
-*/
+ */
 
 /**
  *
  * @package CRM
  * @copyright CiviCRM LLC (c) 2004-2014
  * $Id$
- *
  */
 
 require_once 'HTML/QuickForm/Rule/Email.php';
 
 /**
- * This class contains string functions
+ * This class contains string functions.
  *
  */
 class CRM_Utils_String {
@@ -48,18 +47,13 @@ class CRM_Utils_String {
   const ALPHANUMERIC = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890';
 
   /**
-   * Convert a display name into a potential variable
-   * name that we could use in forms/code
-   *
-   * @param  name    Name of the string
+   * Convert a display name into a potential variable name.
    *
+   * @param $title title of the string
    * @param int $maxLength
    *
-   * @return string  An equivalent variable name
-   *
-   *
-   * @return string (or null)
-   * @static
+   * @return string
+   *   An equivalent variable name.
    */
   public static function titleToVar($title, $maxLength = 31) {
     $variable = self::munge($title, '_', $maxLength);
@@ -74,19 +68,20 @@ class CRM_Utils_String {
   }
 
   /**
-   * Given a string, replace all non alpha numeric characters and
-   * spaces with the replacement character
-   *
-   * @param string $name the name to be worked on
-   * @param string $char the character to use for non-valid chars
-   * @param int    $len  length of valid variables
+   * Replace all non alpha numeric characters and spaces with the replacement character.
    *
+   * @param string $name
+   *   The name to be worked on.
+   * @param string $char
+   *   The character to use for non-valid chars.
+   * @param int $len
+   *   Length of valid variables.
    *
-   * @return string returns the manipulated string
-   * @static
+   * @return string
+   *   returns the manipulated string
    */
   public static function munge($name, $char = '_', $len = 63) {
-    // replace all white space and non-alpha numeric with $char
+    // Replace all white space and non-alpha numeric with $char
     // we only use the ascii character set since mysql does not create table names / field names otherwise
     // CRM-11744
     $name = preg_replace('/[^a-zA-Z0-9]+/', $char, trim($name));
@@ -102,11 +97,11 @@ class CRM_Utils_String {
 
   /**
    * Convert possibly underscore separated words to camel case with special handling for 'UF'
-   * e.g
-   * membership_payment returns MembershipPayment
+   * e.g membership_payment returns MembershipPayment
+   *
    * @param string $string
    *
-   * @return string string
+   * @return string
    */
   public static function convertStringToCamel($string) {
     $fragments = explode('_', $string);
@@ -121,14 +116,15 @@ class CRM_Utils_String {
   }
 
   /**
+   * Takes a variable name and munges it randomly into another variable name.
    *
-   * Takes a variable name and munges it randomly into another variable name
+   * @param string $name
+   *   Initial Variable Name.
+   * @param int $len
+   *   Length of valid variables.
    *
-   * @param  string $name    Initial Variable Name
-   * @param int     $len  length of valid variables
-   *
-   * @return string  Randomized Variable Name
-   * @static
+   * @return string
+   *   Randomized Variable Name
    */
   public static function rename($name, $len = 4) {
     $rand = substr(uniqid(), 0, $len);
@@ -137,14 +133,16 @@ class CRM_Utils_String {
 
   /**
    * Takes a string and returns the last tuple of the string.
-   * useful while converting file names to class names etc
    *
-   * @param string $string the input string
-   * @param \char|string $char $char   the character used to demarcate the componets
+   * Useful while converting file names to class names etc
    *
+   * @param string $string
+   *   The input string.
+   * @param string $char
+   *   Character used to demarcate the components
    *
-   * @return string the last component
-   * @static
+   * @return string
+   *   The last component
    */
   public static function getClassName($string, $char = '_') {
     $names = array();
@@ -157,15 +155,16 @@ class CRM_Utils_String {
   }
 
   /**
-   * Appends a name to a string and seperated by delimiter.
-   * does the right thing for an empty string
+   * Appends a name to a string and separated by delimiter.
    *
-   * @param string $str   the string to be appended to
-   * @param string $delim the delimiter to use
-   * @param mixed  $name  the string (or array of strings) to append
+   * Does the right thing for an empty string
    *
-   * @return void
-   * @static
+   * @param string $str
+   *   The string to be appended to.
+   * @param string $delim
+   *   The delimiter to use.
+   * @param mixed $name
+   *   The string (or array of strings) to append.
    */
   public static function append(&$str, $delim, $name) {
     if (empty($name)) {
@@ -196,13 +195,15 @@ class CRM_Utils_String {
   }
 
   /**
-   * Determine if the string is composed only of ascii characters
+   * Determine if the string is composed only of ascii characters.
    *
-   * @param string  $str input string
-   * @param boolean $utf8 attempt utf8 match on failure (default yes)
+   * @param string $str
+   *   Input string.
+   * @param bool $utf8
+   *   Attempt utf8 match on failure (default yes).
    *
-   * @return boolean    true if string is ascii
-   * @static
+   * @return bool
+   *   true if string is ascii
    */
   public static function isAscii($str, $utf8 = TRUE) {
     if (!function_exists('mb_detect_encoding')) {
@@ -237,14 +238,16 @@ class CRM_Utils_String {
   }
 
   /**
-   * Determine the string replacements for redaction
+   * Determine the string replacements for redaction.
    * on the basis of the regular expressions
    *
-   * @param string $str        input string
-   * @param array  $regexRules regular expression to be matched w/ replacements
+   * @param string $str
+   *   Input string.
+   * @param array $regexRules
+   *   Regular expression to be matched w/ replacements.
    *
-   * @return array $match      array of strings w/ corresponding redacted outputs
-   * @static
+   * @return array
+   *   array of strings w/ corresponding redacted outputs
    */
   public static function regex($str, $regexRules) {
     //redact the regular expressions
@@ -299,10 +302,10 @@ class CRM_Utils_String {
   /**
    * Determine if a string is composed only of utf8 characters
    *
-   * @param string $str  input string
-   * @static
+   * @param string $str
+   *   Input string.
    *
-   * @return boolean
+   * @return bool
    */
   public static function isUtf8($str) {
     if (!function_exists(mb_detect_encoding)) {
@@ -310,9 +313,9 @@ class CRM_Utils_String {
       $str = preg_replace('/\s+/', '', $str);
 
       /* pattern stolen from the php.net function documentation for
-             * utf8decode();
-             * comment by JF Sebastian, 30-Mar-2005
-             */
+       * utf8decode();
+       * comment by JF Sebastian, 30-Mar-2005
+       */
 
       return preg_match('/^([\x00-\x7f]|[\xc2-\xdf][\x80-\xbf]|\xe0[\xa0-\xbf][\x80-\xbf]|[\xe1-\xec][\x80-\xbf]{2}|\xed[\x80-\x9f][\x80-\xbf]|[\xee-\xef][\x80-\xbf]{2}|f0[\x90-\xbf][\x80-\xbf]{2}|[\xf1-\xf3][\x80-\xbf]{3}|\xf4[\x80-\x8f][\x80-\xbf]{2})*$/', $str);
       // ||
@@ -327,11 +330,13 @@ class CRM_Utils_String {
   /**
    * Determine if two href's are equivalent (fuzzy match)
    *
-   * @param string $url1 the first url to be matched
-   * @param string $url2 the second url to be matched against
+   * @param string $url1
+   *   The first url to be matched.
+   * @param string $url2
+   *   The second url to be matched against.
    *
-   * @return boolean true if the urls match, else false
-   * @static
+   * @return bool
+   *   true if the urls match, else false
    */
   public static function match($url1, $url2) {
     $url1 = strtolower($url1);
@@ -349,12 +354,13 @@ class CRM_Utils_String {
   }
 
   /**
-   * Extract variable values
+   * Extract the civicrm path from the url.
    *
-   * @param  mix $query this is basically url
+   * @param string $query
+   *   A url string.
    *
-   * @return mix $v  returns civicrm url (eg: civicrm/contact/search/...)
-   * @static
+   * @return string|null
+   *   civicrm url (eg: civicrm/contact/search)
    */
   public static function extractURLVarValue($query) {
     $config = CRM_Core_Config::singleton();
@@ -375,10 +381,10 @@ class CRM_Utils_String {
   /**
    * Translate a true/false/yes/no string to a 0 or 1 value
    *
-   * @param string $str  the string to be translated
+   * @param string $str
+   *   The string to be translated.
    *
-   * @return boolean
-   * @static
+   * @return bool
    */
   public static function strtobool($str) {
     if (!is_scalar($str)) {
@@ -394,10 +400,10 @@ class CRM_Utils_String {
   /**
    * Returns string '1' for a true/yes/1 string, and '0' for no/false/0 else returns false
    *
-   * @param string $str  the string to be translated
+   * @param string $str
+   *   The string to be translated.
    *
-   * @return boolean
-   * @static
+   * @return bool
    */
   public static function strtoboolstr($str) {
     if (!is_scalar($str)) {
@@ -418,10 +424,11 @@ class CRM_Utils_String {
   /**
    * Convert a HTML string into a text one using html2text
    *
-   * @param string $html  the string to be converted
+   * @param string $html
+   *   The string to be converted.
    *
-   * @return string       the converted string
-   * @static
+   * @return string
+   *   the converted string
    */
   public static function htmlToText($html) {
     require_once 'packages/html2text/rcube_html2text.php';
@@ -509,9 +516,11 @@ class CRM_Utils_String {
    * Given an ezComponents-parsed representation of
    * a text with alternatives return only the first one
    *
-   * @param string $full  all alternatives as a long string (or some other text)
+   * @param string $full
+   *   All alternatives as a long string (or some other text).
    *
-   * @return string       only the first alternative found (or the text without alternatives)
+   * @return string
+   *   only the first alternative found (or the text without alternatives)
    */
   public static function stripAlternatives($full) {
     $matches = array();
@@ -531,27 +540,32 @@ class CRM_Utils_String {
    * Strip leading, trailing, double spaces from string
    * used for postal/greeting/addressee
    *
-   * @param string  $string input string to be cleaned
+   * @param string $string
+   *   Input string to be cleaned.
    *
-   * @return string the cleaned string
-   * @static
+   * @return string
+   *   the cleaned string
    */
   public static function stripSpaces($string) {
     return (empty($string)) ? $string : preg_replace("/\s{2,}/", " ", trim($string));
   }
 
   /**
-   * This function is used to clean the URL 'path' variable that we use
+   * clean the URL 'path' variable that we use
    * to construct CiviCRM urls by removing characters from the path variable
    *
-   * @param string $string  the input string to be sanitized
-   * @param array  $search  the characters to be sanitized
-   * @param string $replace the character to replace it with
+   * @param string $string
+   *   The input string to be sanitized.
+   * @param array $search
+   *   The characters to be sanitized.
+   * @param string $replace
+   *   The character to replace it with.
    *
-   * @return string the sanitized string
-   * @static
+   * @return string
+   *   the sanitized string
    */
-  static function stripPathChars($string,
+  public static function stripPathChars(
+    $string,
     $search = NULL,
     $replace = NULL
   ) {
@@ -564,15 +578,27 @@ class CRM_Utils_String {
 
     if ($_searchChars == NULL) {
       $_searchChars = array(
-        '&', ';', ',', '=', '$',
-        '"', "'", '\\',
-        '<', '>', '(', ')',
-        ' ', "\r", "\r\n", "\n", "\t",
+        '&',
+        ';',
+        ',',
+        '=',
+        '$',
+        '"',
+        "'",
+        '\\',
+        '<',
+        '>',
+        '(',
+        ')',
+        ' ',
+        "\r",
+        "\r\n",
+        "\n",
+        "\t",
       );
       $_replaceChar = '_';
     }
 
-
     if ($search == NULL) {
       $search = $_searchChars;
     }
@@ -590,19 +616,20 @@ class CRM_Utils_String {
    * xss attacks. This is primarily used in public facing pages which
    * accept html as the input string
    *
-   * @param string $string the input string
+   * @param string $string
+   *   The input string.
    *
-   * @return string the cleaned up string
-   * @static
+   * @return string
+   *   the cleaned up string
    */
   public static function purifyHTML($string) {
-    static $_filter = null;
+    static $_filter = NULL;
     if (!$_filter) {
       $config = HTMLPurifier_Config::createDefault();
       $config->set('Core.Encoding', 'UTF-8');
 
       // Disable the cache entirely
-      $config->set('Cache.DefinitionImpl', null);
+      $config->set('Cache.DefinitionImpl', NULL);
 
       $_filter = new HTMLPurifier($config);
     }
@@ -624,12 +651,12 @@ class CRM_Utils_String {
       return $string;
     }
     else {
-      return substr($string, 0, $maxLen-3) . '...';
+      return substr($string, 0, $maxLen - 3) . '...';
     }
   }
 
   /**
-   * Generate a random string
+   * Generate a random string.
    *
    * @param $len
    * @param $alphabet
@@ -650,10 +677,12 @@ class CRM_Utils_String {
    * "cms:admin foo" => array("cms", "admin foo")
    *
    * @param $delim
-   * @param string $string e.g. "view all contacts". Syntax: "[prefix:]name"
+   * @param string $string
+   *   E.g. "view all contacts". Syntax: "[prefix:]name".
    * @param null $defaultPrefix
    *
-   * @return array (0 => string|NULL $prefix, 1 => string $value)
+   * @return array
+   *   (0 => string|NULL $prefix, 1 => string $value)
    */
   public static function parsePrefix($delim, $string, $defaultPrefix = NULL) {
     $pos = strpos($string, $delim);
@@ -661,40 +690,48 @@ class CRM_Utils_String {
       return array($defaultPrefix, $string);
     }
     else {
-      return array(substr($string, 0, $pos), substr($string, 1+$pos));
+      return array(substr($string, 0, $pos), substr($string, 1 + $pos));
     }
   }
 
   /**
    * This function will mask part of the the user portion of an Email address (everything before the @)
    *
-   * @param string $email the email address to be masked
-   * @param string $maskChar the character used for masking
-   * @param integer $percent the percentage of the user portion to be masked
+   * @param string $email
+   *   The email address to be masked.
+   * @param string $maskChar
+   *   The character used for masking.
+   * @param int $percent
+   *   The percentage of the user portion to be masked.
    *
-   * @return string returns the masked Email address
+   * @return string
+   *   returns the masked Email address
    */
-  public static function maskEmail($email, $maskChar= '*', $percent=50) {
+  public static function maskEmail($email, $maskChar = '*', $percent = 50) {
     list($user, $domain) = preg_split("/@/", $email);
     $len = strlen($user);
-    $maskCount = floor($len * $percent /100);
+    $maskCount = floor($len * $percent / 100);
     $offset = floor(($len - $maskCount) / 2);
 
     $masked = substr($user, 0, $offset)
-      .str_repeat($maskChar, $maskCount)
-      .substr($user, $maskCount + $offset);
+      . str_repeat($maskChar, $maskCount)
+      . substr($user, $maskCount + $offset);
 
-    return($masked.'@'.$domain);
+    return ($masked . '@' . $domain);
   }
 
   /**
-   * This function compares two strings
+   * This function compares two strings.
    *
-   * @param string $strOne string one
-   * @param string $strTwo string two
-   * @param boolean $case boolean indicating whether you want the comparison to be case sensitive or not
+   * @param string $strOne
+   *   String one.
+   * @param string $strTwo
+   *   String two.
+   * @param bool $case
+   *   Boolean indicating whether you want the comparison to be case sensitive or not.
    *
-   * @return boolean TRUE (string are identical); FALSE (strings are not identical)
+   * @return bool
+   *   TRUE (string are identical); FALSE (strings are not identical)
    */
   public static function compareStr($strOne, $strTwo, $case) {
     if ($case == TRUE) {
@@ -727,10 +764,28 @@ class CRM_Utils_String {
    * (because most other odd characters are %-escaped in URLs; and %-escaped
    * strings don't need any extra escaping in HTML).
    *
-   * @param string $url URL with HTML entities
-   * @return string URL without HTML entities
+   * @param string $htmlUrl
+   *   URL with HTML entities.
+   * @return string
+   *   URL without HTML entities
    */
   public static function unstupifyUrl($htmlUrl) {
     return str_replace('&amp;', '&', $htmlUrl);
   }
+
+  /**
+   * Formats a string of attributes for insertion in an html tag.
+   *
+   * @param array $attributes
+   *
+   * @return string
+   */
+  public static function htmlAttributes($attributes) {
+    $output = '';
+    foreach ($attributes as $name => $vals) {
+      $output .= " $name=\"" . htmlspecialchars(implode(' ', (array) $vals)) . '"';
+    }
+    return ltrim($output);
+  }
+
 }