MediaWiki REL1_30
ApiResult.php
Go to the documentation of this file.
1<?php
33class ApiResult implements ApiSerializable {
34
39 const OVERRIDE = 1;
40
47 const ADD_ON_TOP = 2;
48
56 const NO_SIZE_CHECK = 4;
57
64 const NO_VALIDATE = 12;
65
70 const META_INDEXED_TAG_NAME = '_element';
71
76 const META_SUBELEMENTS = '_subelements';
77
82 const META_PRESERVE_KEYS = '_preservekeys';
83
88 const META_CONTENT = '_content';
89
108 const META_TYPE = '_type';
109
117 const META_KVP_KEY_NAME = '_kvpkeyname';
118
127 const META_KVP_MERGE = '_kvpmerge';
128
134 const META_BC_BOOLS = '_BC_bools';
135
141 const META_BC_SUBELEMENTS = '_BC_subelements';
142
145
146 // Deprecated fields
148
153 public function __construct( $maxSize ) {
154 if ( $maxSize instanceof ApiMain ) {
155 wfDeprecated( 'ApiMain to ' . __METHOD__, '1.25' );
156 $this->errorFormatter = $maxSize->getErrorFormatter();
157 $this->mainForContinuation = $maxSize;
158 $maxSize = $maxSize->getConfig()->get( 'APIMaxResultSize' );
159 }
160
161 $this->maxSize = $maxSize;
162 $this->checkingSize = true;
163 $this->reset();
164 }
165
171 public function setErrorFormatter( ApiErrorFormatter $formatter ) {
172 $this->errorFormatter = $formatter;
173 }
174
180 public function serializeForApiResult() {
181 return $this->data;
182 }
183
184 /************************************************************************/
192 public function reset() {
193 $this->data = [
194 self::META_TYPE => 'assoc', // Usually what's desired
195 ];
196 $this->size = 0;
197 }
198
252 public function getResultData( $path = [], $transforms = [] ) {
253 $path = (array)$path;
254 if ( !$path ) {
255 return self::applyTransformations( $this->data, $transforms );
256 }
257
258 $last = array_pop( $path );
259 $ret = &$this->path( $path, 'dummy' );
260 if ( !isset( $ret[$last] ) ) {
261 return null;
262 } elseif ( is_array( $ret[$last] ) ) {
263 return self::applyTransformations( $ret[$last], $transforms );
264 } else {
265 return $ret[$last];
266 }
267 }
268
273 public function getSize() {
274 return $this->size;
275 }
276
289 public static function setValue( array &$arr, $name, $value, $flags = 0 ) {
290 if ( ( $flags & self::NO_VALIDATE ) !== self::NO_VALIDATE ) {
292 }
293
294 if ( $name === null ) {
295 if ( $flags & self::ADD_ON_TOP ) {
296 array_unshift( $arr, $value );
297 } else {
298 array_push( $arr, $value );
299 }
300 return;
301 }
302
303 $exists = isset( $arr[$name] );
304 if ( !$exists || ( $flags & self::OVERRIDE ) ) {
305 if ( !$exists && ( $flags & self::ADD_ON_TOP ) ) {
306 $arr = [ $name => $value ] + $arr;
307 } else {
308 $arr[$name] = $value;
309 }
310 } elseif ( is_array( $arr[$name] ) && is_array( $value ) ) {
311 $conflicts = array_intersect_key( $arr[$name], $value );
312 if ( !$conflicts ) {
313 $arr[$name] += $value;
314 } else {
315 $keys = implode( ', ', array_keys( $conflicts ) );
316 throw new RuntimeException(
317 "Conflicting keys ($keys) when attempting to merge element $name"
318 );
319 }
320 } else {
321 throw new RuntimeException(
322 "Attempting to add element $name=$value, existing value is {$arr[$name]}"
323 );
324 }
325 }
326
332 private static function validateValue( $value ) {
333 global $wgContLang;
334
335 if ( is_object( $value ) ) {
336 // Note we use is_callable() here instead of instanceof because
337 // ApiSerializable is an informal protocol (see docs there for details).
338 if ( is_callable( [ $value, 'serializeForApiResult' ] ) ) {
339 $oldValue = $value;
340 $value = $value->serializeForApiResult();
341 if ( is_object( $value ) ) {
342 throw new UnexpectedValueException(
343 get_class( $oldValue ) . '::serializeForApiResult() returned an object of class ' .
344 get_class( $value )
345 );
346 }
347
348 // Recursive call instead of fall-through so we can throw a
349 // better exception message.
350 try {
351 return self::validateValue( $value );
352 } catch ( Exception $ex ) {
353 throw new UnexpectedValueException(
354 get_class( $oldValue ) . '::serializeForApiResult() returned an invalid value: ' .
355 $ex->getMessage(),
356 0,
357 $ex
358 );
359 }
360 } elseif ( is_callable( [ $value, '__toString' ] ) ) {
362 } else {
363 $value = (array)$value + [ self::META_TYPE => 'assoc' ];
364 }
365 }
366 if ( is_array( $value ) ) {
367 // Work around https://bugs.php.net/bug.php?id=45959 by copying to a temporary
368 // (in this case, foreach gets $k === "1" but $tmp[$k] assigns as if $k === 1)
369 $tmp = [];
370 foreach ( $value as $k => $v ) {
371 $tmp[$k] = self::validateValue( $v );
372 }
373 $value = $tmp;
374 } elseif ( is_float( $value ) && !is_finite( $value ) ) {
375 throw new InvalidArgumentException( 'Cannot add non-finite floats to ApiResult' );
376 } elseif ( is_string( $value ) ) {
377 $value = $wgContLang->normalize( $value );
378 } elseif ( $value !== null && !is_scalar( $value ) ) {
379 $type = gettype( $value );
380 if ( is_resource( $value ) ) {
381 $type .= '(' . get_resource_type( $value ) . ')';
382 }
383 throw new InvalidArgumentException( "Cannot add $type to ApiResult" );
384 }
385
386 return $value;
387 }
388
405 public function addValue( $path, $name, $value, $flags = 0 ) {
406 $arr = &$this->path( $path, ( $flags & self::ADD_ON_TOP ) ? 'prepend' : 'append' );
407
408 if ( $this->checkingSize && !( $flags & self::NO_SIZE_CHECK ) ) {
409 // self::size needs the validated value. Then flag
410 // to not re-validate later.
413
414 $newsize = $this->size + self::size( $value );
415 if ( $this->maxSize !== false && $newsize > $this->maxSize ) {
416 $this->errorFormatter->addWarning(
417 'result', [ 'apiwarn-truncatedresult', Message::numParam( $this->maxSize ) ]
418 );
419 return false;
420 }
421 $this->size = $newsize;
422 }
423
424 self::setValue( $arr, $name, $value, $flags );
425 return true;
426 }
427
434 public static function unsetValue( array &$arr, $name ) {
435 $ret = null;
436 if ( isset( $arr[$name] ) ) {
437 $ret = $arr[$name];
438 unset( $arr[$name] );
439 }
440 return $ret;
441 }
442
453 public function removeValue( $path, $name, $flags = 0 ) {
454 $path = (array)$path;
455 if ( $name === null ) {
456 if ( !$path ) {
457 throw new InvalidArgumentException( 'Cannot remove the data root' );
458 }
459 $name = array_pop( $path );
460 }
461 $ret = self::unsetValue( $this->path( $path, 'dummy' ), $name );
462 if ( $this->checkingSize && !( $flags & self::NO_SIZE_CHECK ) ) {
463 $newsize = $this->size - self::size( $ret );
464 $this->size = max( $newsize, 0 );
465 }
466 return $ret;
467 }
468
478 public static function setContentValue( array &$arr, $name, $value, $flags = 0 ) {
479 if ( $name === null ) {
480 throw new InvalidArgumentException( 'Content value must be named' );
481 }
482 self::setContentField( $arr, $name, $flags );
483 self::setValue( $arr, $name, $value, $flags );
484 }
485
496 public function addContentValue( $path, $name, $value, $flags = 0 ) {
497 if ( $name === null ) {
498 throw new InvalidArgumentException( 'Content value must be named' );
499 }
500 $this->addContentField( $path, $name, $flags );
501 $this->addValue( $path, $name, $value, $flags );
502 }
503
511 public function addParsedLimit( $moduleName, $limit ) {
512 // Add value, allowing overwriting
513 $this->addValue( 'limits', $moduleName, $limit,
514 self::OVERRIDE | self::NO_SIZE_CHECK );
515 }
516
519 /************************************************************************/
532 public static function setContentField( array &$arr, $name, $flags = 0 ) {
533 if ( isset( $arr[self::META_CONTENT] ) &&
534 isset( $arr[$arr[self::META_CONTENT]] ) &&
535 !( $flags & self::OVERRIDE )
536 ) {
537 throw new RuntimeException(
538 "Attempting to set content element as $name when " . $arr[self::META_CONTENT] .
539 ' is already set as the content element'
540 );
541 }
543 }
544
553 public function addContentField( $path, $name, $flags = 0 ) {
554 $arr = &$this->path( $path, ( $flags & self::ADD_ON_TOP ) ? 'prepend' : 'append' );
555 self::setContentField( $arr, $name, $flags );
556 }
557
565 public static function setSubelementsList( array &$arr, $names ) {
566 if ( !isset( $arr[self::META_SUBELEMENTS] ) ) {
567 $arr[self::META_SUBELEMENTS] = (array)$names;
568 } else {
569 $arr[self::META_SUBELEMENTS] = array_merge( $arr[self::META_SUBELEMENTS], (array)$names );
570 }
571 }
572
580 public function addSubelementsList( $path, $names ) {
581 $arr = &$this->path( $path );
582 self::setSubelementsList( $arr, $names );
583 }
584
592 public static function unsetSubelementsList( array &$arr, $names ) {
593 if ( isset( $arr[self::META_SUBELEMENTS] ) ) {
594 $arr[self::META_SUBELEMENTS] = array_diff( $arr[self::META_SUBELEMENTS], (array)$names );
595 }
596 }
597
605 public function removeSubelementsList( $path, $names ) {
606 $arr = &$this->path( $path );
607 self::unsetSubelementsList( $arr, $names );
608 }
609
616 public static function setIndexedTagName( array &$arr, $tag ) {
617 if ( !is_string( $tag ) ) {
618 throw new InvalidArgumentException( 'Bad tag name' );
619 }
620 $arr[self::META_INDEXED_TAG_NAME] = $tag;
621 }
622
629 public function addIndexedTagName( $path, $tag ) {
630 $arr = &$this->path( $path );
631 self::setIndexedTagName( $arr, $tag );
632 }
633
641 public static function setIndexedTagNameRecursive( array &$arr, $tag ) {
642 if ( !is_string( $tag ) ) {
643 throw new InvalidArgumentException( 'Bad tag name' );
644 }
645 $arr[self::META_INDEXED_TAG_NAME] = $tag;
646 foreach ( $arr as $k => &$v ) {
647 if ( !self::isMetadataKey( $k ) && is_array( $v ) ) {
649 }
650 }
651 }
652
660 public function addIndexedTagNameRecursive( $path, $tag ) {
661 $arr = &$this->path( $path );
663 }
664
675 public static function setPreserveKeysList( array &$arr, $names ) {
676 if ( !isset( $arr[self::META_PRESERVE_KEYS] ) ) {
677 $arr[self::META_PRESERVE_KEYS] = (array)$names;
678 } else {
679 $arr[self::META_PRESERVE_KEYS] = array_merge( $arr[self::META_PRESERVE_KEYS], (array)$names );
680 }
681 }
682
690 public function addPreserveKeysList( $path, $names ) {
691 $arr = &$this->path( $path );
692 self::setPreserveKeysList( $arr, $names );
693 }
694
702 public static function unsetPreserveKeysList( array &$arr, $names ) {
703 if ( isset( $arr[self::META_PRESERVE_KEYS] ) ) {
704 $arr[self::META_PRESERVE_KEYS] = array_diff( $arr[self::META_PRESERVE_KEYS], (array)$names );
705 }
706 }
707
715 public function removePreserveKeysList( $path, $names ) {
716 $arr = &$this->path( $path );
717 self::unsetPreserveKeysList( $arr, $names );
718 }
719
728 public static function setArrayType( array &$arr, $type, $kvpKeyName = null ) {
729 if ( !in_array( $type, [
730 'default', 'array', 'assoc', 'kvp', 'BCarray', 'BCassoc', 'BCkvp'
731 ], true ) ) {
732 throw new InvalidArgumentException( 'Bad type' );
733 }
734 $arr[self::META_TYPE] = $type;
735 if ( is_string( $kvpKeyName ) ) {
736 $arr[self::META_KVP_KEY_NAME] = $kvpKeyName;
737 }
738 }
739
747 public function addArrayType( $path, $tag, $kvpKeyName = null ) {
748 $arr = &$this->path( $path );
749 self::setArrayType( $arr, $tag, $kvpKeyName );
750 }
751
759 public static function setArrayTypeRecursive( array &$arr, $type, $kvpKeyName = null ) {
760 self::setArrayType( $arr, $type, $kvpKeyName );
761 foreach ( $arr as $k => &$v ) {
762 if ( !self::isMetadataKey( $k ) && is_array( $v ) ) {
763 self::setArrayTypeRecursive( $v, $type, $kvpKeyName );
764 }
765 }
766 }
767
775 public function addArrayTypeRecursive( $path, $tag, $kvpKeyName = null ) {
776 $arr = &$this->path( $path );
777 self::setArrayTypeRecursive( $arr, $tag, $kvpKeyName );
778 }
779
782 /************************************************************************/
793 public static function isMetadataKey( $key ) {
794 return substr( $key, 0, 1 ) === '_';
795 }
796
806 protected static function applyTransformations( array $dataIn, array $transforms ) {
807 $strip = isset( $transforms['Strip'] ) ? $transforms['Strip'] : 'none';
808 if ( $strip === 'base' ) {
809 $transforms['Strip'] = 'none';
810 }
811 $transformTypes = isset( $transforms['Types'] ) ? $transforms['Types'] : null;
812 if ( $transformTypes !== null && !is_array( $transformTypes ) ) {
813 throw new InvalidArgumentException( __METHOD__ . ':Value for "Types" must be an array' );
814 }
815
816 $metadata = [];
817 $data = self::stripMetadataNonRecursive( $dataIn, $metadata );
818
819 if ( isset( $transforms['Custom'] ) ) {
820 if ( !is_callable( $transforms['Custom'] ) ) {
821 throw new InvalidArgumentException( __METHOD__ . ': Value for "Custom" must be callable' );
822 }
823 call_user_func_array( $transforms['Custom'], [ &$data, &$metadata ] );
824 }
825
826 if ( ( isset( $transforms['BC'] ) || $transformTypes !== null ) &&
827 isset( $metadata[self::META_TYPE] ) && $metadata[self::META_TYPE] === 'BCkvp' &&
828 !isset( $metadata[self::META_KVP_KEY_NAME] )
829 ) {
830 throw new UnexpectedValueException( 'Type "BCkvp" used without setting ' .
831 'ApiResult::META_KVP_KEY_NAME metadata item' );
832 }
833
834 // BC transformations
835 $boolKeys = null;
836 if ( isset( $transforms['BC'] ) ) {
837 if ( !is_array( $transforms['BC'] ) ) {
838 throw new InvalidArgumentException( __METHOD__ . ':Value for "BC" must be an array' );
839 }
840 if ( !in_array( 'nobool', $transforms['BC'], true ) ) {
841 $boolKeys = isset( $metadata[self::META_BC_BOOLS] )
842 ? array_flip( $metadata[self::META_BC_BOOLS] )
843 : [];
844 }
845
846 if ( !in_array( 'no*', $transforms['BC'], true ) &&
847 isset( $metadata[self::META_CONTENT] ) && $metadata[self::META_CONTENT] !== '*'
848 ) {
849 $k = $metadata[self::META_CONTENT];
850 $data['*'] = $data[$k];
851 unset( $data[$k] );
852 $metadata[self::META_CONTENT] = '*';
853 }
854
855 if ( !in_array( 'nosub', $transforms['BC'], true ) &&
856 isset( $metadata[self::META_BC_SUBELEMENTS] )
857 ) {
858 foreach ( $metadata[self::META_BC_SUBELEMENTS] as $k ) {
859 if ( isset( $data[$k] ) ) {
860 $data[$k] = [
861 '*' => $data[$k],
862 self::META_CONTENT => '*',
863 self::META_TYPE => 'assoc',
864 ];
865 }
866 }
867 }
868
869 if ( isset( $metadata[self::META_TYPE] ) ) {
870 switch ( $metadata[self::META_TYPE] ) {
871 case 'BCarray':
872 case 'BCassoc':
873 $metadata[self::META_TYPE] = 'default';
874 break;
875 case 'BCkvp':
876 $transformTypes['ArmorKVP'] = $metadata[self::META_KVP_KEY_NAME];
877 break;
878 }
879 }
880 }
881
882 // Figure out type, do recursive calls, and do boolean transform if necessary
883 $defaultType = 'array';
884 $maxKey = -1;
885 foreach ( $data as $k => &$v ) {
886 $v = is_array( $v ) ? self::applyTransformations( $v, $transforms ) : $v;
887 if ( $boolKeys !== null && is_bool( $v ) && !isset( $boolKeys[$k] ) ) {
888 if ( !$v ) {
889 unset( $data[$k] );
890 continue;
891 }
892 $v = '';
893 }
894 if ( is_string( $k ) ) {
895 $defaultType = 'assoc';
896 } elseif ( $k > $maxKey ) {
897 $maxKey = $k;
898 }
899 }
900 unset( $v );
901
902 // Determine which metadata to keep
903 switch ( $strip ) {
904 case 'all':
905 case 'base':
906 $keepMetadata = [];
907 break;
908 case 'none':
909 $keepMetadata = &$metadata;
910 break;
911 case 'bc':
912 $keepMetadata = array_intersect_key( $metadata, [
913 self::META_INDEXED_TAG_NAME => 1,
914 self::META_SUBELEMENTS => 1,
915 ] );
916 break;
917 default:
918 throw new InvalidArgumentException( __METHOD__ . ': Unknown value for "Strip"' );
919 }
920
921 // Type transformation
922 if ( $transformTypes !== null ) {
923 if ( $defaultType === 'array' && $maxKey !== count( $data ) - 1 ) {
924 $defaultType = 'assoc';
925 }
926
927 // Override type, if provided
928 $type = $defaultType;
929 if ( isset( $metadata[self::META_TYPE] ) && $metadata[self::META_TYPE] !== 'default' ) {
930 $type = $metadata[self::META_TYPE];
931 }
932 if ( ( $type === 'kvp' || $type === 'BCkvp' ) &&
933 empty( $transformTypes['ArmorKVP'] )
934 ) {
935 $type = 'assoc';
936 } elseif ( $type === 'BCarray' ) {
937 $type = 'array';
938 } elseif ( $type === 'BCassoc' ) {
939 $type = 'assoc';
940 }
941
942 // Apply transformation
943 switch ( $type ) {
944 case 'assoc':
945 $metadata[self::META_TYPE] = 'assoc';
946 $data += $keepMetadata;
947 return empty( $transformTypes['AssocAsObject'] ) ? $data : (object)$data;
948
949 case 'array':
950 ksort( $data );
951 $data = array_values( $data );
952 $metadata[self::META_TYPE] = 'array';
953 return $data + $keepMetadata;
954
955 case 'kvp':
956 case 'BCkvp':
957 $key = isset( $metadata[self::META_KVP_KEY_NAME] )
958 ? $metadata[self::META_KVP_KEY_NAME]
959 : $transformTypes['ArmorKVP'];
960 $valKey = isset( $transforms['BC'] ) ? '*' : 'value';
961 $assocAsObject = !empty( $transformTypes['AssocAsObject'] );
962 $merge = !empty( $metadata[self::META_KVP_MERGE] );
963
964 $ret = [];
965 foreach ( $data as $k => $v ) {
966 if ( $merge && ( is_array( $v ) || is_object( $v ) ) ) {
967 $vArr = (array)$v;
968 if ( isset( $vArr[self::META_TYPE] ) ) {
969 $mergeType = $vArr[self::META_TYPE];
970 } elseif ( is_object( $v ) ) {
971 $mergeType = 'assoc';
972 } else {
973 $keys = array_keys( $vArr );
974 sort( $keys, SORT_NUMERIC );
975 $mergeType = ( $keys === array_keys( $keys ) ) ? 'array' : 'assoc';
976 }
977 } else {
978 $mergeType = 'n/a';
979 }
980 if ( $mergeType === 'assoc' ) {
981 $item = $vArr + [
982 $key => $k,
983 ];
984 if ( $strip === 'none' ) {
985 self::setPreserveKeysList( $item, [ $key ] );
986 }
987 } else {
988 $item = [
989 $key => $k,
990 $valKey => $v,
991 ];
992 if ( $strip === 'none' ) {
993 $item += [
994 self::META_PRESERVE_KEYS => [ $key ],
995 self::META_CONTENT => $valKey,
996 self::META_TYPE => 'assoc',
997 ];
998 }
999 }
1000 $ret[] = $assocAsObject ? (object)$item : $item;
1001 }
1002 $metadata[self::META_TYPE] = 'array';
1003
1004 return $ret + $keepMetadata;
1005
1006 default:
1007 throw new UnexpectedValueException( "Unknown type '$type'" );
1008 }
1009 } else {
1010 return $data + $keepMetadata;
1011 }
1012 }
1013
1024 public static function stripMetadata( $data ) {
1025 if ( is_array( $data ) || is_object( $data ) ) {
1026 $isObj = is_object( $data );
1027 if ( $isObj ) {
1028 $data = (array)$data;
1029 }
1030 $preserveKeys = isset( $data[self::META_PRESERVE_KEYS] )
1031 ? (array)$data[self::META_PRESERVE_KEYS]
1032 : [];
1033 foreach ( $data as $k => $v ) {
1034 if ( self::isMetadataKey( $k ) && !in_array( $k, $preserveKeys, true ) ) {
1035 unset( $data[$k] );
1036 } elseif ( is_array( $v ) || is_object( $v ) ) {
1037 $data[$k] = self::stripMetadata( $v );
1038 }
1039 }
1040 if ( $isObj ) {
1041 $data = (object)$data;
1042 }
1043 }
1044 return $data;
1045 }
1046
1058 public static function stripMetadataNonRecursive( $data, &$metadata = null ) {
1059 if ( !is_array( $metadata ) ) {
1060 $metadata = [];
1061 }
1062 if ( is_array( $data ) || is_object( $data ) ) {
1063 $isObj = is_object( $data );
1064 if ( $isObj ) {
1065 $data = (array)$data;
1066 }
1067 $preserveKeys = isset( $data[self::META_PRESERVE_KEYS] )
1068 ? (array)$data[self::META_PRESERVE_KEYS]
1069 : [];
1070 foreach ( $data as $k => $v ) {
1071 if ( self::isMetadataKey( $k ) && !in_array( $k, $preserveKeys, true ) ) {
1072 $metadata[$k] = $v;
1073 unset( $data[$k] );
1074 }
1075 }
1076 if ( $isObj ) {
1077 $data = (object)$data;
1078 }
1079 }
1080 return $data;
1081 }
1082
1089 private static function size( $value ) {
1090 $s = 0;
1091 if ( is_array( $value ) ) {
1092 foreach ( $value as $k => $v ) {
1093 if ( !self::isMetadataKey( $k ) ) {
1094 $s += self::size( $v );
1095 }
1096 }
1097 } elseif ( is_scalar( $value ) ) {
1098 $s = strlen( $value );
1099 }
1100
1101 return $s;
1102 }
1103
1115 private function &path( $path, $create = 'append' ) {
1116 $path = (array)$path;
1117 $ret = &$this->data;
1118 foreach ( $path as $i => $k ) {
1119 if ( !isset( $ret[$k] ) ) {
1120 switch ( $create ) {
1121 case 'append':
1122 $ret[$k] = [];
1123 break;
1124 case 'prepend':
1125 $ret = [ $k => [] ] + $ret;
1126 break;
1127 case 'dummy':
1128 $tmp = [];
1129 return $tmp;
1130 default:
1131 $fail = implode( '.', array_slice( $path, 0, $i + 1 ) );
1132 throw new InvalidArgumentException( "Path $fail does not exist" );
1133 }
1134 }
1135 if ( !is_array( $ret[$k] ) ) {
1136 $fail = implode( '.', array_slice( $path, 0, $i + 1 ) );
1137 throw new InvalidArgumentException( "Path $fail is not an array" );
1138 }
1139 $ret = &$ret[$k];
1140 }
1141 return $ret;
1142 }
1143
1152 public static function addMetadataToResultVars( $vars, $forceHash = true ) {
1153 // Process subarrays and determine if this is a JS [] or {}
1154 $hash = $forceHash;
1155 $maxKey = -1;
1156 $bools = [];
1157 foreach ( $vars as $k => $v ) {
1158 if ( is_array( $v ) || is_object( $v ) ) {
1159 $vars[$k] = self::addMetadataToResultVars( (array)$v, is_object( $v ) );
1160 } elseif ( is_bool( $v ) ) {
1161 // Better here to use real bools even in BC formats
1162 $bools[] = $k;
1163 }
1164 if ( is_string( $k ) ) {
1165 $hash = true;
1166 } elseif ( $k > $maxKey ) {
1167 $maxKey = $k;
1168 }
1169 }
1170 if ( !$hash && $maxKey !== count( $vars ) - 1 ) {
1171 $hash = true;
1172 }
1173
1174 // Set metadata appropriately
1175 if ( $hash ) {
1176 // Get the list of keys we actually care about. Unfortunately, we can't support
1177 // certain keys that conflict with ApiResult metadata.
1178 $keys = array_diff( array_keys( $vars ), [
1179 self::META_TYPE, self::META_PRESERVE_KEYS, self::META_KVP_KEY_NAME,
1180 self::META_INDEXED_TAG_NAME, self::META_BC_BOOLS
1181 ] );
1182
1183 return [
1184 self::META_TYPE => 'kvp',
1185 self::META_KVP_KEY_NAME => 'key',
1186 self::META_PRESERVE_KEYS => $keys,
1187 self::META_BC_BOOLS => $bools,
1188 self::META_INDEXED_TAG_NAME => 'var',
1189 ] + $vars;
1190 } else {
1191 return [
1192 self::META_TYPE => 'array',
1193 self::META_BC_BOOLS => $bools,
1194 self::META_INDEXED_TAG_NAME => 'value',
1195 ] + $vars;
1196 }
1197 }
1198
1207 public static function formatExpiry( $expiry, $infinity = 'infinity' ) {
1208 static $dbInfinity;
1209 if ( $dbInfinity === null ) {
1210 $dbInfinity = wfGetDB( DB_REPLICA )->getInfinity();
1211 }
1212
1213 if ( $expiry === '' || $expiry === null || $expiry === false ||
1214 wfIsInfinity( $expiry ) || $expiry === $dbInfinity
1215 ) {
1216 return $infinity;
1217 } else {
1218 return wfTimestamp( TS_ISO_8601, $expiry );
1219 }
1220 }
1221
1224}
1225
wfGetDB( $db, $groups=[], $wiki=false)
Get a Database object.
wfIsInfinity( $str)
Determine input string is represents as infinity.
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
wfDeprecated( $function, $version=false, $component=false, $callerOffset=2)
Throws a warning that $function is deprecated.
Formats errors and warnings for the API, and add them to the associated ApiResult.
This is the main API class, used for both external and internal processing.
Definition ApiMain.php:45
This class represents the result of the API operations.
Definition ApiResult.php:33
addArrayType( $path, $tag, $kvpKeyName=null)
Set the array data type for a path.
static unsetSubelementsList(array &$arr, $names)
Causes the elements with the specified names to be output as attributes (when possible) rather than a...
static unsetPreserveKeysList(array &$arr, $names)
Don't preserve specified keys.
static applyTransformations(array $dataIn, array $transforms)
Apply transformations to an array, returning the transformed array.
const META_TYPE
Key for the 'type' metadata item.
static stripMetadataNonRecursive( $data, &$metadata=null)
Remove metadata keys from a data array or object, non-recursive.
static setArrayType(array &$arr, $type, $kvpKeyName=null)
Set the array data type.
serializeForApiResult()
Allow for adding one ApiResult into another.
static addMetadataToResultVars( $vars, $forceHash=true)
Add the correct metadata to an array of vars we want to export through the API.
static setValue(array &$arr, $name, $value, $flags=0)
Add an output value to the array by name.
static validateValue( $value)
Validate a value for addition to the result.
const META_SUBELEMENTS
Key for the 'subelements' metadata item.
Definition ApiResult.php:76
addIndexedTagName( $path, $tag)
Set the tag name for numeric-keyed values in XML format.
addValue( $path, $name, $value, $flags=0)
Add value to the output data at the given path.
const META_BC_BOOLS
Key for the 'BC bools' metadata item.
const META_PRESERVE_KEYS
Key for the 'preserve keys' metadata item.
Definition ApiResult.php:82
const NO_SIZE_CHECK
For addValue() and similar functions, do not check size while adding a value Don't use this unless yo...
Definition ApiResult.php:56
addArrayTypeRecursive( $path, $tag, $kvpKeyName=null)
Set the array data type for a path recursively.
getSize()
Get the size of the result, i.e.
__construct( $maxSize)
static unsetValue(array &$arr, $name)
Remove an output value to the array by name.
static setPreserveKeysList(array &$arr, $names)
Preserve specified keys.
addPreserveKeysList( $path, $names)
Preserve specified keys.
addParsedLimit( $moduleName, $limit)
Add the numeric limit for a limit=max to the result.
addSubelementsList( $path, $names)
Causes the elements with the specified names to be output as subelements rather than attributes.
static stripMetadata( $data)
Recursively remove metadata keys from a data array or object.
const META_CONTENT
Key for the 'content' metadata item.
Definition ApiResult.php:88
addIndexedTagNameRecursive( $path, $tag)
Set indexed tag name on $path and all subarrays.
removeSubelementsList( $path, $names)
Causes the elements with the specified names to be output as attributes (when possible) rather than a...
setErrorFormatter(ApiErrorFormatter $formatter)
Set the error formatter.
const OVERRIDE
Override existing value in addValue(), setValue(), and similar functions.
Definition ApiResult.php:39
& path( $path, $create='append')
Return a reference to the internal data at $path.
static setSubelementsList(array &$arr, $names)
Causes the elements with the specified names to be output as subelements rather than attributes.
static setArrayTypeRecursive(array &$arr, $type, $kvpKeyName=null)
Set the array data type recursively.
const META_KVP_KEY_NAME
Key for the metadata item whose value specifies the name used for the kvp key in the alternative outp...
removeValue( $path, $name, $flags=0)
Remove value from the output data at the given path.
const ADD_ON_TOP
For addValue(), setValue() and similar functions, if the value does not exist, add it as the first el...
Definition ApiResult.php:47
getResultData( $path=[], $transforms=[])
Get the result data array.
const META_BC_SUBELEMENTS
Key for the 'BC subelements' metadata item.
removePreserveKeysList( $path, $names)
Don't preserve specified keys.
static setIndexedTagName(array &$arr, $tag)
Set the tag name for numeric-keyed values in XML format.
const META_INDEXED_TAG_NAME
Key for the 'indexed tag name' metadata item.
Definition ApiResult.php:70
const META_KVP_MERGE
Key for the metadata item that indicates that the KVP key should be added into an assoc value,...
reset()
Clear the current result data.
static setContentValue(array &$arr, $name, $value, $flags=0)
Add an output value to the array by name and mark as META_CONTENT.
static setIndexedTagNameRecursive(array &$arr, $tag)
Set indexed tag name on $arr and all subarrays.
static setContentField(array &$arr, $name, $flags=0)
Set the name of the content field name (META_CONTENT)
static size( $value)
Get the 'real' size of a result item.
static formatExpiry( $expiry, $infinity='infinity')
Format an expiry timestamp for API output.
const NO_VALIDATE
For addValue(), setValue() and similar functions, do not validate data.
Definition ApiResult.php:64
addContentValue( $path, $name, $value, $flags=0)
Add value to the output data at the given path and mark as META_CONTENT.
addContentField( $path, $name, $flags=0)
Set the name of the content field name (META_CONTENT)
static isMetadataKey( $key)
Test whether a key should be considered metadata.
this class mediates it Skin Encapsulates a look and feel for the wiki All of the functions that render HTML and make choices about how to render it are here and are called from various other places when and is meant to be subclassed with other skins that may override some of its functions The User object contains a reference to a and so rather than having a global skin object we just rely on the global User and get the skin with $wgUser and also has some character encoding functions and other locale stuff The current user interface language is instantiated as and the local content language as $wgContLang
Definition design.txt:57
the array() calling protocol came about after MediaWiki 1.4rc1.
static configuration should be added through ResourceLoaderGetConfigVars instead & $vars
Definition hooks.txt:2198
This code would result in ircNotify being run twice when an article is and once for brion Hooks can return three possible true was required This is the default since MediaWiki *some string
Definition hooks.txt:181
it s the revision text itself In either if gzip is the revision text is gzipped $flags
Definition hooks.txt:2805
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses & $ret
Definition hooks.txt:1975
Allows to change the fields on the form that will be generated $name
Definition hooks.txt:302
globals will be eliminated from MediaWiki replaced by an application object which would be passed to constructors Whether that would be an convenient solution remains to be but certainly PHP makes such object oriented programming models easier than they were in previous versions For the time being MediaWiki programmers will have to work in an environment with some global context At the time of globals were initialised on startup by MediaWiki of these were configuration which are documented in DefaultSettings php There is no comprehensive documentation for the remaining however some of the most important ones are listed below They are typically initialised either in index php or in Setup php For a description of the see design txt $wgTitle Title object created from the request URL $wgOut OutputPage object for HTTP response $wgUser User object for the user associated with the current request $wgLang Language object selected by user preferences $wgContLang Language object associated with the wiki being viewed $wgParser Parser object Parser extensions register their hooks here $wgRequest WebRequest object
Definition globals.txt:64
This interface allows for overriding the default conversion applied by ApiResult::validateValue().
$last
const DB_REPLICA
Definition defines.php:25