3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
17 class CRM_Utils_Type
{
36 // @TODO What's the point of these constants? Backwards compatibility?
38 // These are used for field size (<input type=text size=2>), but redundant TWO=2
39 // usages are rare and should be eliminated. See CRM-18810.
55 * Maximum size of a MySQL BLOB or TEXT column in bytes.
57 const BLOB_SIZE
= 65535;
60 * Maximum value of a MySQL signed INT column.
62 const INT_MAX
= 2147483647;
65 * Gets the string representation for a data type.
68 * Integer number identifying the data type.
71 * String identifying the data type, e.g. 'Int' or 'String'.
73 public static function typeToString($type) {
74 // @todo Use constants in the case statements, e.g. "case T_INT:".
75 // @todo return directly, instead of assigning a value.
76 // @todo Use a lookup array, as a property or as a local variable.
113 $string = 'Timestamp';
133 $string = 'Mediumblob';
137 return (isset($string)) ?
$string : "";
142 * An array of type in the form 'type name' => 'int representing type'
144 public static function getValidTypes() {
146 'Int' => self
::T_INT
,
147 'String' => self
::T_STRING
,
148 'Enum' => self
::T_ENUM
,
149 'Date' => self
::T_DATE
,
150 'Time' => self
::T_TIME
,
151 'Boolean' => self
::T_BOOLEAN
,
152 'Text' => self
::T_TEXT
,
153 'Blob' => self
::T_BLOB
,
154 'Timestamp' => self
::T_TIMESTAMP
,
155 'Float' => self
::T_FLOAT
,
156 'Money' => self
::T_MONEY
,
157 'Email' => self
::T_EMAIL
,
158 'Mediumblob' => self
::T_MEDIUMBLOB
,
163 * Get the data_type for the field.
165 * @param array $fieldMetadata
166 * Metadata about the field.
170 public static function getDataTypeFromFieldMetadata($fieldMetadata) {
171 if (isset($fieldMetadata['data_type'])) {
172 return $fieldMetadata['data_type'];
174 if (empty($fieldMetadata['type'])) {
175 // I would prefer to throw an e-notice but there is some,
176 // probably unnecessary logic, that only retrieves activity fields
177 // if they are 'in the profile' and probably they are not 'in'
178 // until they are added - which might lead to ? who knows!
181 return self
::typeToString($fieldMetadata['type']);
185 * Helper function to call escape on arrays.
189 public static function escapeAll($data, $type, $abort = TRUE) {
190 foreach ($data as $key => $value) {
191 $data[$key] = CRM_Utils_Type
::escape($value, $type, $abort);
197 * Helper function to call validate on arrays
200 * @param string $type
204 * @throws \CRM_Core_Exception
208 public static function validateAll($data, $type) {
209 foreach ($data as $key => $value) {
210 $data[$key] = CRM_Utils_Type
::validate($value, $type);
216 * Verify that a variable is of a given type, and apply a bit of processing.
219 * The value to be verified/escaped.
220 * @param string $type
221 * The type to verify against.
223 * If TRUE, the operation will throw an CRM_Core_Exception on invalid data.
226 * The data, escaped if necessary.
227 * @throws CRM_Core_Exception
229 public static function escape($data, $type, $abort = TRUE) {
238 case 'ContactReference':
239 case 'MysqlOrderByDirection':
240 $validatedData = self
::validate($data, $type, $abort);
241 if (isset($validatedData)) {
242 return $validatedData;
246 // CRM-8925 for custom fields of this type
248 case 'StateProvince':
249 // Handle multivalued data in delimited or array format
250 if (is_array($data) ||
(strpos($data, CRM_Core_DAO
::VALUE_SEPARATOR
) !== FALSE)) {
252 foreach (CRM_Utils_Array
::explodePadded($data) as $item) {
253 if (!CRM_Utils_Rule
::positiveInteger($item)) {
261 elseif (CRM_Utils_Rule
::positiveInteger($data)) {
267 if (CRM_Utils_Rule
::positiveInteger($data)) {
273 if (CRM_Utils_Rule
::url($data = trim($data))) {
279 if (CRM_Utils_Rule
::boolean($data)) {
287 return CRM_Core_DAO
::escapeString(self
::validate($data, $type, $abort));
289 case 'MysqlColumnNameOrAlias':
290 if (CRM_Utils_Rule
::mysqlColumnNameOrAlias($data)) {
291 $data = str_replace('`', '', $data);
292 $parts = explode('.', $data);
293 $data = '`' . implode('`.`', $parts) . '`';
300 if (CRM_Utils_Rule
::mysqlOrderBy($data)) {
301 $parts = explode(',', $data);
303 // The field() syntax is tricky here because it uses commas & when
304 // we separate by them we break it up. But we want to keep the clauses in order.
305 // so we just clumsily re-assemble it. Test cover exists.
306 $fieldClauseStart = NULL;
307 foreach ($parts as $index => &$part) {
308 if (substr($part, 0, 6) === 'field(') {
309 // Looking to escape a string like 'field(contribution_status_id,3,4,5) asc'
310 // to 'field(`contribution_status_id`,3,4,5) asc'
311 $fieldClauseStart = $index;
314 if ($fieldClauseStart !== NULL) {
315 // this is part of the list of field options. Concatenate it back on.
316 $parts[$fieldClauseStart] .= ',' . $part;
317 unset($parts[$index]);
318 if (!strstr($parts[$fieldClauseStart], ')')) {
319 // we have not reached the end of the list.
322 // We have the last piece of the field() clause, time to escape it.
323 $parts[$fieldClauseStart] = self
::mysqlOrderByFieldFunctionCallback($parts[$fieldClauseStart]);
324 $fieldClauseStart = NULL;
329 $part = preg_replace_callback('/^(?:(?:((?:`[\w-]{1,64}`|[\w-]{1,64}))(?:\.))?(`[\w-]{1,64}`|[\w-]{1,64})(?: (asc|desc))?)$/i', ['CRM_Utils_Type', 'mysqlOrderByCallback'], trim($part));
331 return implode(', ', $parts);
336 throw new CRM_Core_Exception(
337 $type . " is not a recognised (camel cased) data type."
341 // @todo Use exceptions instead of CRM_Core_Error::fatal().
343 $data = htmlentities($data);
345 throw new CRM_Core_Exception("$data is not of the type $type");
351 * Verify that a variable is of a given type.
354 * The value to validate.
355 * @param string $type
356 * The type to validate against.
358 * If TRUE, the operation will CRM_Core_Error::fatal() on invalid data.
359 * @param string $name
360 * The name of the attribute
363 * The data, escaped if necessary
365 * @throws \CRM_Core_Exception
367 public static function validate($data, $type, $abort = TRUE, $name = 'One of parameters ') {
373 'CommaSeparatedIntegers',
384 'MysqlColumnNameOrAlias',
385 'MysqlOrderByDirection',
392 if (!in_array($type, $possibleTypes)) {
393 throw new CRM_Core_Exception(ts('Invalid type, must be one of : ' . implode($possibleTypes)));
398 if (CRM_Utils_Rule
::integer($data)) {
404 if (CRM_Utils_Rule
::positiveInteger($data)) {
411 if (CRM_Utils_Rule
::numeric($data)) {
424 // a null timestamp is valid
425 if (strlen(trim($data)) == 0) {
429 if ((preg_match('/^\d{14}$/', $data) ||
430 preg_match('/^\d{8}$/', $data)
432 CRM_Utils_Rule
::mysqlDate($data)
438 case 'ContactReference':
440 if (strlen(trim($data)) == 0) {
444 if (CRM_Utils_Rule
::validContact($data)) {
449 case 'MysqlOrderByDirection':
450 if (CRM_Utils_Rule
::mysqlOrderByDirection($data)) {
451 return strtolower($data);
456 if (CRM_Utils_Rule
::checkExtensionKeyIsValid($data)) {
462 $check = lcfirst($type);
463 if (CRM_Utils_Rule
::$check($data)) {
469 $data = htmlentities($data);
470 throw new CRM_Core_Exception("$name (value: $data) is not of the type $type");
477 * Validate that a value matches a PHP type.
479 * Note that, at a micro-level, this is probably slower than using real PHP type-checking, but it doesn't seem bad.
480 * (In light benchmarking of ~1000 validations on an i3-10100, there is no obvious effect on the execution-time.)
481 * Should be fast enough for validating business entities.
483 * Example usage: 'validatePhpType(123, 'int|double');`
485 * @param mixed $value
486 * @param string|string[] $types
487 * The list of acceptable PHP types and/or classnames.
488 * Either an array or a string (with '|' delimiters).
489 * Note that 'null' is a distinct type.
491 * Ex: 'Countable|null'
494 * @param bool $isStrict
495 * If data is likely to come from another text medium, then you may want to
496 * allow (say) numbers and string-like-numbers to be used interchangably.
498 * With $isStrict=TRUE, the string "123" does not match type "int". The int 456 does not match type "double". etc.
500 * With $isStrict=FALSE, the string "123" will match types "string", "int", and "double".
503 public static function validatePhpType($value, $types, bool $isStrict = TRUE) {
504 if (is_string($types)) {
505 $types = preg_split('/ *\| */', $types);
508 $checkTypeStrict = function($type, $value) {
509 static $aliases = ['integer' => 'int', 'boolean' => 'bool', 'float' => 'double', 'NULL' => 'null'];
518 $expectBool = mb_strtolower($type) === 'true';
519 return $value === $expectBool;
521 $realType = gettype($value);
522 if (($aliases[$realType] ??
$realType) === ($aliases[$type] ??
$type)) {
525 if ($realType === 'object' && $value instanceof $type) {
530 $checkTypeRelaxed = function($type, $value) use ($checkTypeStrict) {
533 return is_string($value) ||
is_int($value) ||
is_float($value);
537 return is_bool($value) || CRM_Utils_Rule
::integer($value);
541 return CRM_Utils_Rule
::integer($value);
545 return CRM_Utils_Rule
::numeric($value);
548 return $checkTypeStrict($type, $value);
551 $checkType = $isStrict ?
$checkTypeStrict : $checkTypeRelaxed;
553 foreach ($types as $type) {
554 $isTypedArray = substr($type, -2, 2) === '[]';
555 if (!$isTypedArray && $checkType($type, $value)) {
558 if ($isTypedArray && is_array($value)) {
559 $baseType = substr($type, 0, -2);
560 foreach ($value as $vItem) {
561 if (!\CRM_Utils_Type
::validatePhpType($vItem, [$baseType], $isStrict)) {
572 * Preg_replace_callback for mysqlOrderByFieldFunction escape.
574 * Add backticks around the field name.
576 * @param string $clause
580 public static function mysqlOrderByFieldFunctionCallback($clause) {
581 return preg_replace('/field\((\w*)/', 'field(`${1}`', $clause);
585 * preg_replace_callback for MysqlOrderBy escape.
587 public static function mysqlOrderByCallback($matches) {
589 $matches = str_replace('`', '', $matches);
592 if (isset($matches[1]) && $matches[1]) {
593 $output .= '`' . $matches[1] . '`.';
597 if (isset($matches[2]) && $matches[2]) {
598 $output .= '`' . $matches[2] . '`';
602 if (isset($matches[3]) && $matches[3]) {
603 $output .= ' ' . $matches[3];
610 * Get list of avaliable Data Types for Option Groups
614 public static function dataTypes() {
624 return array_combine($types, $types);
628 * Get all the types that are text-like.
630 * The returned types would all legitimately be compared to '' by mysql
634 * WHERE display_name = '' is valid
635 * WHERE id = '' is not and in some mysql configurations and queries
636 * could cause an error.
640 public static function getTextTypes(): array {