CRM/Utils/Type.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2018                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2018
  32  */
  33 class CRM_Utils_Type {
  34   const
  35     T_INT = 1,
  36     T_STRING = 2,
  37     T_ENUM = 2,
  38     T_DATE = 4,
  39     T_TIME = 8,
  40     T_BOOLEAN = 16,
  41     T_TEXT = 32,
  42     T_LONGTEXT = 32,
  43     T_BLOB = 64,
  44     T_TIMESTAMP = 256,
  45     T_FLOAT = 512,
  46     T_MONEY = 1024,
  47     T_EMAIL = 2048,
  48     T_URL = 4096,
  49     T_CCNUM = 8192,
  50     T_MEDIUMBLOB = 16384;
  51
  52   // @TODO What's the point of these constants? Backwards compatibility?
  53   //
  54   // These are used for field size (<input type=text size=2>), but redundant TWO=2
  55   // usages are rare and should be eliminated. See CRM-18810.
  56   const
  57     TWO = 2,
  58     FOUR = 4,
  59     SIX = 6,
  60     EIGHT = 8,
  61     TWELVE = 12,
  62     SIXTEEN = 16,
  63     TWENTY = 20,
  64     MEDIUM = 20,
  65     THIRTY = 30,
  66     BIG = 30,
  67     FORTYFIVE = 45,
  68     HUGE = 45;
  69
  70   /**
  71    * Gets the string representation for a data type.
  72    *
  73    * @param int $type
  74    *   Integer number identifying the data type.
  75    *
  76    * @return string
  77    *   String identifying the data type, e.g. 'Int' or 'String'.
  78    */
  79   public static function typeToString($type) {
  80     // @todo Use constants in the case statements, e.g. "case T_INT:".
  81     // @todo return directly, instead of assigning a value.
  82     // @todo Use a lookup array, as a property or as a local variable.
  83     switch ($type) {
  84       case 1:
  85         $string = 'Int';
  86         break;
  87
  88       case 2:
  89         $string = 'String';
  90         break;
  91
  92       case 3:
  93         $string = 'Enum';
  94         break;
  95
  96       case 4:
  97         $string = 'Date';
  98         break;
  99
 100       case 8:
 101         $string = 'Time';
 102         break;
 103
 104       case 16:
 105         $string = 'Boolean';
 106         break;
 107
 108       case 32:
 109         $string = 'Text';
 110         break;
 111
 112       case 64:
 113         $string = 'Blob';
 114         break;
 115
 116       // CRM-10404
 117       case 12:
 118       case 256:
 119         $string = 'Timestamp';
 120         break;
 121
 122       case 512:
 123         $string = 'Float';
 124         break;
 125
 126       case 1024:
 127         $string = 'Money';
 128         break;
 129
 130       case 2048:
 131         $string = 'Date';
 132         break;
 133
 134       case 4096:
 135         $string = 'Email';
 136         break;
 137
 138       case 16384:
 139         $string = 'Mediumblob';
 140         break;
 141     }
 142
 143     return (isset($string)) ? $string : "";
 144   }
 145
 146   /**
 147    * @return array
 148    *   An array of type in the form 'type name' => 'int representing type'
 149    */
 150   public static function getValidTypes() {
 151     return array(
 152       'Int' => self::T_INT,
 153       'String' => self::T_STRING,
 154       'Enum' => self::T_ENUM,
 155       'Date' => self::T_DATE,
 156       'Time' => self::T_TIME,
 157       'Boolean' => self::T_BOOLEAN,
 158       'Text' => self::T_TEXT,
 159       'Blob' => self::T_BLOB,
 160       'Timestamp' => self::T_TIMESTAMP,
 161       'Float' => self::T_FLOAT,
 162       'Money' => self::T_MONEY,
 163       'Email' => self::T_EMAIL,
 164       'Mediumblob' => self::T_MEDIUMBLOB,
 165     );
 166   }
 167
 168   /**
 169    * Get the data_type for the field.
 170    *
 171    * @param array $fieldMetadata
 172    *   Metadata about the field.
 173    *
 174    * @return string
 175    */
 176   public static function getDataTypeFromFieldMetadata($fieldMetadata) {
 177     if (isset($fieldMetadata['data_type'])) {
 178       return $fieldMetadata['data_type'];
 179     }
 180     if (empty($fieldMetadata['type'])) {
 181       // I would prefer to throw an e-notice but there is some,
 182       // probably unnecessary logic, that only retrieves activity fields
 183       // if they are 'in the profile' and probably they are not 'in'
 184       // until they are added - which might lead to ? who knows!
 185       return '';
 186     }
 187     return self::typeToString($fieldMetadata['type']);
 188   }
 189
 190   /**
 191    * Helper function to call escape on arrays.
 192    *
 193    * @see escape
 194    */
 195   public static function escapeAll($data, $type, $abort = TRUE) {
 196     foreach ($data as $key => $value) {
 197       $data[$key] = CRM_Utils_Type::escape($value, $type, $abort);
 198     }
 199     return $data;
 200   }
 201
 202   /**
 203    * Helper function to call validate on arrays
 204    *
 205    * @see validate
 206    */
 207   public static function validateAll($data, $type, $abort = TRUE) {
 208     foreach ($data as $key => $value) {
 209       $data[$key] = CRM_Utils_Type::validate($value, $type, $abort);
 210     }
 211     return $data;
 212   }
 213
 214   /**
 215    * Verify that a variable is of a given type, and apply a bit of processing.
 216    *
 217    * @param mixed $data
 218    *   The value to be verified/escaped.
 219    * @param string $type
 220    *   The type to verify against.
 221    * @param bool $abort
 222    *   If TRUE, the operation will CRM_Core_Error::fatal() on invalid data.
 223    *
 224    * @return mixed
 225    *   The data, escaped if necessary.
 226    */
 227   public static function escape($data, $type, $abort = TRUE) {
 228     switch ($type) {
 229       case 'Integer':
 230       case 'Int':
 231         if (CRM_Utils_Rule::integer($data)) {
 232           return (int) $data;
 233         }
 234         break;
 235
 236       case 'Positive':
 237         if (CRM_Utils_Rule::positiveInteger($data)) {
 238           return (int) $data;
 239         }
 240         break;
 241
 242       // CRM-8925 for custom fields of this type
 243       case 'Country':
 244       case 'StateProvince':
 245         // Handle multivalued data in delimited or array format
 246         if (is_array($data) || (strpos($data, CRM_Core_DAO::VALUE_SEPARATOR) !== FALSE)) {
 247           $valid = TRUE;
 248           foreach (CRM_Utils_Array::explodePadded($data) as $item) {
 249             if (!CRM_Utils_Rule::positiveInteger($item)) {
 250               $valid = FALSE;
 251             }
 252           }
 253           if ($valid) {
 254             return $data;
 255           }
 256         }
 257         elseif (CRM_Utils_Rule::positiveInteger($data)) {
 258           return (int) $data;
 259         }
 260         break;
 261
 262       case 'File':
 263         if (CRM_Utils_Rule::positiveInteger($data)) {
 264           return (int) $data;
 265         }
 266         break;
 267
 268       case 'Link':
 269         if (CRM_Utils_Rule::url($data = trim($data))) {
 270           return $data;
 271         }
 272         break;
 273
 274       case 'Boolean':
 275         if (CRM_Utils_Rule::boolean($data)) {
 276           return $data;
 277         }
 278         break;
 279
 280       case 'Float':
 281       case 'Money':
 282         if (CRM_Utils_Rule::numeric($data)) {
 283           return $data;
 284         }
 285         break;
 286
 287       case 'String':
 288       case 'Memo':
 289       case 'Text':
 290         return CRM_Core_DAO::escapeString($data);
 291
 292       case 'Date':
 293       case 'Timestamp':
 294         // a null date or timestamp is valid
 295         if (strlen(trim($data)) == 0) {
 296           return trim($data);
 297         }
 298
 299         if ((preg_match('/^\d{8}$/', $data) ||
 300             preg_match('/^\d{14}$/', $data)
 301           ) &&
 302           CRM_Utils_Rule::mysqlDate($data)
 303         ) {
 304           return $data;
 305         }
 306         break;
 307
 308       case 'ContactReference':
 309         if (strlen(trim($data)) == 0) {
 310           return trim($data);
 311         }
 312
 313         if (CRM_Utils_Rule::validContact($data)) {
 314           return (int) $data;
 315         }
 316         break;
 317
 318       case 'MysqlColumnNameOrAlias':
 319         if (CRM_Utils_Rule::mysqlColumnNameOrAlias($data)) {
 320           $data = str_replace('`', '', $data);
 321           $parts = explode('.', $data);
 322           $data = '`' . implode('`.`', $parts) . '`';
 323
 324           return $data;
 325         }
 326         break;
 327
 328       case 'MysqlOrderByDirection':
 329         if (CRM_Utils_Rule::mysqlOrderByDirection($data)) {
 330           return strtolower($data);
 331         }
 332         break;
 333
 334       case 'MysqlOrderBy':
 335         if (CRM_Utils_Rule::mysqlOrderBy($data)) {
 336           $parts = explode(',', $data);
 337
 338           // The field() syntax is tricky here because it uses commas & when
 339           // we separate by them we break it up. But we want to keep the clauses in order.
 340           // so we just clumsily re-assemble it. Test cover exists.
 341           $fieldClauseStart = NULL;
 342           foreach ($parts as $index => &$part) {
 343             if (substr($part, 0, 6) === 'field(') {
 344               // Looking to escape a string like 'field(contribution_status_id,3,4,5) asc'
 345               // to 'field(`contribution_status_id`,3,4,5) asc'
 346               $fieldClauseStart = $index;
 347               continue;
 348             }
 349             if ($fieldClauseStart !== NULL) {
 350               // this is part of the list of field options. Concatenate it back on.
 351               $parts[$fieldClauseStart] .= ',' . $part;
 352               unset($parts[$index]);
 353               if (!strstr($parts[$fieldClauseStart], ')')) {
 354                 // we have not reached the end of the list.
 355                 continue;
 356               }
 357               // We have the last piece of the field() clause, time to escape it.
 358               $parts[$fieldClauseStart] = self::mysqlOrderByFieldFunctionCallback($parts[$fieldClauseStart]);
 359               $fieldClauseStart = NULL;
 360               continue;
 361
 362             }
 363             // Normal clause.
 364             $part = preg_replace_callback('/^(?:(?:((?:`[\w-]{1,64}`|[\w-]{1,64}))(?:\.))?(`[\w-]{1,64}`|[\w-]{1,64})(?: (asc|desc))?)$/i', array('CRM_Utils_Type', 'mysqlOrderByCallback'), trim($part));
 365           }
 366           return implode(', ', $parts);
 367         }
 368         break;
 369
 370       default:
 371         CRM_Core_Error::fatal(
 372           $type . " is not a recognised (camel cased) data type."
 373         );
 374         break;
 375     }
 376
 377     // @todo Use exceptions instead of CRM_Core_Error::fatal().
 378     if ($abort) {
 379       $data = htmlentities($data);
 380       CRM_Core_Error::fatal("$data is not of the type $type");
 381     }
 382     return NULL;
 383   }
 384
 385   /**
 386    * Verify that a variable is of a given type.
 387    *
 388    * @param mixed $data
 389    *   The value to validate.
 390    * @param string $type
 391    *   The type to validate against.
 392    * @param bool $abort
 393    *   If TRUE, the operation will CRM_Core_Error::fatal() on invalid data.
 394    * @param string $name
 395    *   The name of the attribute
 396    * @param bool $isThrowException
 397    *   Should an exception be thrown rather than a using a deprecated fatal error.
 398    *
 399    * @return mixed
 400    *   The data, escaped if necessary
 401    *
 402    * @throws \CRM_Core_Exception
 403    */
 404   public static function validate($data, $type, $abort = TRUE, $name = 'One of parameters ', $isThrowException = FALSE) {
 405
 406     $possibleTypes = array(
 407       'Integer',
 408       'Int',
 409       'Positive',
 410       'CommaSeparatedIntegers',
 411       'Boolean',
 412       'Float',
 413       'Money',
 414       'Text',
 415       'String',
 416       'Link',
 417       'Memo',
 418       'Date',
 419       'Timestamp',
 420       'ContactReference',
 421       'MysqlColumnNameOrAlias',
 422       'MysqlOrderByDirection',
 423       'MysqlOrderBy',
 424       'ExtensionKey',
 425       'Json',
 426       'Alphanumeric',
 427     );
 428     if (!in_array($type, $possibleTypes)) {
 429       if ($isThrowException) {
 430         throw new CRM_Core_Exception(ts('Invalid type, must be one of : ' . implode($possibleTypes)));
 431       }
 432       CRM_Core_Error::fatal(ts('Invalid type, must be one of : ' . implode($possibleTypes)));
 433     }
 434     switch ($type) {
 435       case 'Integer':
 436       case 'Int':
 437         if (CRM_Utils_Rule::integer($data)) {
 438           return (int) $data;
 439         }
 440         break;
 441
 442       case 'Positive':
 443         if (CRM_Utils_Rule::positiveInteger($data)) {
 444           return (int) $data;
 445         }
 446         break;
 447
 448       case 'CommaSeparatedIntegers':
 449         if (CRM_Utils_Rule::commaSeparatedIntegers($data)) {
 450           return $data;
 451         }
 452         break;
 453
 454       case 'Boolean':
 455         if (CRM_Utils_Rule::boolean($data)) {
 456           return $data;
 457         }
 458         break;
 459
 460       case 'Float':
 461       case 'Money':
 462         if (CRM_Utils_Rule::numeric($data)) {
 463           return $data;
 464         }
 465         break;
 466
 467       case 'Text':
 468       case 'String':
 469       case 'Link':
 470       case 'Memo':
 471         return $data;
 472
 473       case 'Date':
 474         // a null date is valid
 475         if (strlen(trim($data)) == 0) {
 476           return trim($data);
 477         }
 478
 479         if (preg_match('/^\d{8}$/', $data) &&
 480           CRM_Utils_Rule::mysqlDate($data)
 481         ) {
 482           return $data;
 483         }
 484         break;
 485
 486       case 'Timestamp':
 487         // a null timestamp is valid
 488         if (strlen(trim($data)) == 0) {
 489           return trim($data);
 490         }
 491
 492         if ((preg_match('/^\d{14}$/', $data) ||
 493             preg_match('/^\d{8}$/', $data)
 494           ) &&
 495           CRM_Utils_Rule::mysqlDate($data)
 496         ) {
 497           return $data;
 498         }
 499         break;
 500
 501       case 'ContactReference':
 502         // null is valid
 503         if (strlen(trim($data)) == 0) {
 504           return trim($data);
 505         }
 506
 507         if (CRM_Utils_Rule::validContact($data)) {
 508           return $data;
 509         }
 510         break;
 511
 512       case 'MysqlColumnNameOrAlias':
 513         if (CRM_Utils_Rule::mysqlColumnNameOrAlias($data)) {
 514           return $data;
 515         }
 516         break;
 517
 518       case 'MysqlOrderByDirection':
 519         if (CRM_Utils_Rule::mysqlOrderByDirection($data)) {
 520           return strtolower($data);
 521         }
 522         break;
 523
 524       case 'MysqlOrderBy':
 525         if (CRM_Utils_Rule::mysqlOrderBy($data)) {
 526           return $data;
 527         }
 528         break;
 529
 530       case 'ExtensionKey':
 531         if (CRM_Utils_Rule::checkExtensionKeyIsValid($data)) {
 532           return $data;
 533         }
 534         break;
 535
 536       case 'Json':
 537         if (CRM_Utils_Rule::json($data)) {
 538           return $data;
 539         }
 540         break;
 541
 542       case 'Alphanumeric':
 543         if (CRM_Utils_Rule::alphanumeric($data)) {
 544           return $data;
 545         }
 546         break;
 547     }
 548
 549     if ($abort) {
 550       $data = htmlentities($data);
 551       if ($isThrowException) {
 552         throw new CRM_Core_Exception("$name (value: $data) is not of the type $type");
 553       }
 554       CRM_Core_Error::fatal("$name (value: $data) is not of the type $type");
 555     }
 556
 557     return NULL;
 558   }
 559
 560   /**
 561    * Preg_replace_callback for mysqlOrderByFieldFunction escape.
 562    *
 563    * Add backticks around the field name.
 564    *
 565    * @param string $clause
 566    *
 567    * @return string
 568    */
 569   public static function mysqlOrderByFieldFunctionCallback($clause) {
 570     return preg_replace('/field\((\w*)/', 'field(`${1}`', $clause);
 571   }
 572
 573   /**
 574    * preg_replace_callback for MysqlOrderBy escape.
 575    */
 576   public static function mysqlOrderByCallback($matches) {
 577     $output = '';
 578     $matches = str_replace('`', '', $matches);
 579
 580     // Table name.
 581     if (isset($matches[1]) && $matches[1]) {
 582       $output .= '`' . $matches[1] . '`.';
 583     }
 584
 585     // Column name.
 586     if (isset($matches[2]) && $matches[2]) {
 587       $output .= '`' . $matches[2] . '`';
 588     }
 589
 590     // Sort order.
 591     if (isset($matches[3]) && $matches[3]) {
 592       $output .= ' ' . $matches[3];
 593     }
 594
 595     return $output;
 596   }
 597
 598   /**
 599    * Get list of avaliable Data Types for Option Groups
 600    *
 601    * @return array
 602    */
 603   public static function dataTypes() {
 604     $types = array(
 605       'Integer',
 606       'String',
 607       'Date',
 608       'Time',
 609       'Timestamp',
 610       'Money',
 611       'Email',
 612     );
 613     return array_combine($types, $types);
 614   }
 615
 616 }