MediaWiki  1.29.1
ApiResult.php
Go to the documentation of this file.
1 <?php
33 class 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 
143  private $data, $size, $maxSize;
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 ) {
292  }
293 
294  if ( $name === null ) {
295  if ( $flags & ApiResult::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 & ApiResult::OVERRIDE ) ) {
305  if ( !$exists && ( $flags & ApiResult::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 ) {
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' ] ) ) {
361  $value = (string)$value;
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 & ApiResult::ADD_ON_TOP ) ? 'prepend' : 'append' );
407 
408  if ( $this->checkingSize && !( $flags & ApiResult::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 & ApiResult::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  }
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,
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  }
542  $arr[self::META_CONTENT] = $name;
543  }
544 
553  public function addContentField( $path, $name, $flags = 0 ) {
554  $arr = &$this->path( $path, ( $flags & ApiResult::ADD_ON_TOP ) ? 'prepend' : 'append' );
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  }
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  }
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] = ApiResult::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 ), [
1181  ] );
1182 
1183  return [
1184  ApiResult::META_TYPE => 'kvp',
1187  ApiResult::META_BC_BOOLS => $bools,
1189  ] + $vars;
1190  } else {
1191  return [
1192  ApiResult::META_TYPE => 'array',
1193  ApiResult::META_BC_BOOLS => $bools,
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 
ApiResult\addPreserveKeysList
addPreserveKeysList( $path, $names)
Preserve specified keys.
Definition: ApiResult.php:690
ApiResult\__construct
__construct( $maxSize)
Definition: ApiResult.php:153
ApiMain
This is the main API class, used for both external and internal processing.
Definition: ApiMain.php:45
ApiResult\addIndexedTagName
addIndexedTagName( $path, $tag)
Set the tag name for numeric-keyed values in XML format.
Definition: ApiResult.php:629
object
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:25
ApiSerializable
This interface allows for overriding the default conversion applied by ApiResult::validateValue().
Definition: ApiSerializable.php:37
ApiResult\$checkingSize
$checkingSize
Definition: ApiResult.php:147
captcha-old.count
count
Definition: captcha-old.py:225
ApiResult\setContentField
static setContentField(array &$arr, $name, $flags=0)
Set the name of the content field name (META_CONTENT)
Definition: ApiResult.php:532
ApiResult\META_TYPE
const META_TYPE
Key for the 'type' metadata item.
Definition: ApiResult.php:108
$last
$last
Definition: profileinfo.php:415
wfTimestamp
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
Definition: GlobalFunctions.php:1994
ApiResult\META_BC_SUBELEMENTS
const META_BC_SUBELEMENTS
Key for the 'BC subelements' metadata item.
Definition: ApiResult.php:141
ApiResult\setArrayTypeRecursive
static setArrayTypeRecursive(array &$arr, $type, $kvpKeyName=null)
Set the array data type recursively.
Definition: ApiResult.php:759
ApiResult\META_PRESERVE_KEYS
const META_PRESERVE_KEYS
Key for the 'preserve keys' metadata item.
Definition: ApiResult.php:82
ApiResult\$size
$size
Definition: ApiResult.php:143
ApiResult\addContentField
addContentField( $path, $name, $flags=0)
Set the name of the content field name (META_CONTENT)
Definition: ApiResult.php:553
ApiResult\applyTransformations
static applyTransformations(array $dataIn, array $transforms)
Apply transformations to an array, returning the transformed array.
Definition: ApiResult.php:806
ApiResult\setValue
static setValue(array &$arr, $name, $value, $flags=0)
Add an output value to the array by name.
Definition: ApiResult.php:289
$s
$s
Definition: mergeMessageFileList.php:188
ApiResult\NO_SIZE_CHECK
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
$name
Allows to change the fields on the form that will be generated $name
Definition: hooks.txt:304
ApiResult\META_KVP_KEY_NAME
const META_KVP_KEY_NAME
Key for the metadata item whose value specifies the name used for the kvp key in the alternative outp...
Definition: ApiResult.php:117
ApiResult\removeSubelementsList
removeSubelementsList( $path, $names)
Causes the elements with the specified names to be output as attributes (when possible) rather than a...
Definition: ApiResult.php:605
$type
do that in ParserLimitReportFormat instead use this to modify the parameters of the image and a DIV can begin in one section and end in another Make sure your code can handle that case gracefully See the EditSectionClearerLink extension for an example zero but section is usually empty its values are the globals values before the output is cached my talk my contributions etc etc otherwise the built in rate limiting checks are if enabled allows for interception of redirect as a string mapping parameter names to values & $type
Definition: hooks.txt:2536
ApiResult\addArrayTypeRecursive
addArrayTypeRecursive( $path, $tag, $kvpKeyName=null)
Set the array data type for a path recursively.
Definition: ApiResult.php:775
ApiResult\NO_VALIDATE
const NO_VALIDATE
For addValue(), setValue() and similar functions, do not validate data.
Definition: ApiResult.php:64
ApiResult\serializeForApiResult
serializeForApiResult()
Allow for adding one ApiResult into another.
Definition: ApiResult.php:180
ApiResult\addContentValue
addContentValue( $path, $name, $value, $flags=0)
Add value to the output data at the given path and mark as META_CONTENT.
Definition: ApiResult.php:496
php
injection txt This is an overview of how MediaWiki makes use of dependency injection The design described here grew from the discussion of RFC T384 The term dependency this means that anything an object needs to operate should be injected from the the object itself should only know narrow no concrete implementation of the logic it relies on The requirement to inject everything typically results in an architecture that based on two main types of and essentially stateless service objects that use other service objects to operate on the value objects As of the beginning MediaWiki is only starting to use the DI approach Much of the code still relies on global state or direct resulting in a highly cyclical dependency which acts as the top level factory for services in MediaWiki which can be used to gain access to default instances of various services MediaWikiServices however also allows new services to be defined and default services to be redefined Services are defined or redefined by providing a callback the instantiator that will return a new instance of the service When it will create an instance of MediaWikiServices and populate it with the services defined in the files listed by thereby bootstrapping the DI framework Per $wgServiceWiringFiles lists includes ServiceWiring php
Definition: injection.txt:35
ApiResult\path
& path( $path, $create='append')
Return a reference to the internal data at $path.
Definition: ApiResult.php:1115
ApiResult\getSize
getSize()
Get the size of the result, i.e.
Definition: ApiResult.php:273
ApiResult\addArrayType
addArrayType( $path, $tag, $kvpKeyName=null)
Set the array data type for a path.
Definition: ApiResult.php:747
ApiResult\setContentValue
static setContentValue(array &$arr, $name, $value, $flags=0)
Add an output value to the array by name and mark as META_CONTENT.
Definition: ApiResult.php:478
ApiResult\$mainForContinuation
$mainForContinuation
Definition: ApiResult.php:147
ApiResult\setArrayType
static setArrayType(array &$arr, $type, $kvpKeyName=null)
Set the array data type.
Definition: ApiResult.php:728
ApiResult\META_INDEXED_TAG_NAME
const META_INDEXED_TAG_NAME
Key for the 'indexed tag name' metadata item.
Definition: ApiResult.php:70
ApiResult\addParsedLimit
addParsedLimit( $moduleName, $limit)
Add the numeric limit for a limit=max to the result.
Definition: ApiResult.php:511
wfDeprecated
wfDeprecated( $function, $version=false, $component=false, $callerOffset=2)
Throws a warning that $function is deprecated.
Definition: GlobalFunctions.php:1128
ApiResult\addMetadataToResultVars
static addMetadataToResultVars( $vars, $forceHash=true)
Add the correct metadata to an array of vars we want to export through the API.
Definition: ApiResult.php:1152
ApiResult
This class represents the result of the API operations.
Definition: ApiResult.php:33
wfGetDB
wfGetDB( $db, $groups=[], $wiki=false)
Get a Database object.
Definition: GlobalFunctions.php:3060
$tag
this hook is for auditing only RecentChangesLinked and Watchlist RecentChangesLinked and Watchlist Do not use this to implement individual filters if they are compatible with the ChangesListFilter and ChangesListFilterGroup structure use sub classes of those in conjunction with the ChangesListSpecialPageStructuredFilters hook This hook can be used to implement filters that do not implement that or custom behavior that is not an individual filter e g Watchlist and Watchlist you will want to construct new ChangesListBooleanFilter or ChangesListStringOptionsFilter objects When constructing you specify which group they belong to You can reuse existing or create your you must register them with $special registerFilterGroup removed from all revisions and log entries to which it was applied This gives extensions a chance to take it off their books $tag
Definition: hooks.txt:1028
ApiResult\META_SUBELEMENTS
const META_SUBELEMENTS
Key for the 'subelements' metadata item.
Definition: ApiResult.php:76
ApiResult\unsetValue
static unsetValue(array &$arr, $name)
Remove an output value to the array by name.
Definition: ApiResult.php:434
ApiResult\validateValue
static validateValue( $value)
Validate a value for addition to the result.
Definition: ApiResult.php:332
$limit
this hook is for auditing only RecentChangesLinked and Watchlist RecentChangesLinked and Watchlist Do not use this to implement individual filters if they are compatible with the ChangesListFilter and ChangesListFilterGroup structure use sub classes of those in conjunction with the ChangesListSpecialPageStructuredFilters hook This hook can be used to implement filters that do not implement that or custom behavior that is not an individual filter e g Watchlist and Watchlist you will want to construct new ChangesListBooleanFilter or ChangesListStringOptionsFilter objects When constructing you specify which group they belong to You can reuse existing or create your you must register them with $special registerFilterGroup removed from all revisions and log entries to which it was applied This gives extensions a chance to take it off their books as the deletion has already been partly carried out by this point or something similar the user will be unable to create the tag set and then return false from the hook function Ensure you consume the ChangeTagAfterDelete hook to carry out custom deletion actions as context called by AbstractContent::getParserOutput May be used to override the normal model specific rendering of page content as context as context the output can only depend on parameters provided to this hook not on global state indicating whether full HTML should be generated If generation of HTML may be but other information should still be present in the ParserOutput object to manipulate or replace but no entry for that model exists in $wgContentHandlers please use GetContentModels hook to make them known to core if desired whether it is OK to use $contentModel on $title Handler functions that modify $ok should generally return false to prevent further hooks from further modifying $ok inclusive $limit
Definition: hooks.txt:1049
ApiResult\reset
reset()
Clear the current result data.
Definition: ApiResult.php:192
ApiResult\META_BC_BOOLS
const META_BC_BOOLS
Key for the 'BC bools' metadata item.
Definition: ApiResult.php:134
ApiResult\stripMetadataNonRecursive
static stripMetadataNonRecursive( $data, &$metadata=null)
Remove metadata keys from a data array or object, non-recursive.
Definition: ApiResult.php:1058
global
when a variable name is used in a it is silently declared as a new masking the global
Definition: design.txt:93
$vars
static configuration should be added through ResourceLoaderGetConfigVars instead & $vars
Definition: hooks.txt:2179
DB_REPLICA
const DB_REPLICA
Definition: defines.php:25
ApiResult\$errorFormatter
$errorFormatter
Definition: ApiResult.php:144
string
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:177
ApiResult\removeValue
removeValue( $path, $name, $flags=0)
Remove value from the output data at the given path.
Definition: ApiResult.php:453
ApiResult\addValue
addValue( $path, $name, $value, $flags=0)
Add value to the output data at the given path.
Definition: ApiResult.php:405
ApiResult\setErrorFormatter
setErrorFormatter(ApiErrorFormatter $formatter)
Set the error formatter.
Definition: ApiResult.php:171
ApiResult\unsetPreserveKeysList
static unsetPreserveKeysList(array &$arr, $names)
Don't preserve specified keys.
Definition: ApiResult.php:702
ApiResult\addSubelementsList
addSubelementsList( $path, $names)
Causes the elements with the specified names to be output as subelements rather than attributes.
Definition: ApiResult.php:580
ApiResult\setIndexedTagName
static setIndexedTagName(array &$arr, $tag)
Set the tag name for numeric-keyed values in XML format.
Definition: ApiResult.php:616
$value
$value
Definition: styleTest.css.php:45
ApiResult\size
static size( $value)
Get the 'real' size of a result item.
Definition: ApiResult.php:1089
wfIsInfinity
wfIsInfinity( $str)
Determine input string is represents as infinity.
Definition: GlobalFunctions.php:3577
$ret
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:1956
ApiResult\removePreserveKeysList
removePreserveKeysList( $path, $names)
Don't preserve specified keys.
Definition: ApiResult.php:715
ApiResult\isMetadataKey
static isMetadataKey( $key)
Test whether a key should be considered metadata.
Definition: ApiResult.php:793
ApiErrorFormatter
Formats errors and warnings for the API, and add them to the associated ApiResult.
Definition: ApiErrorFormatter.php:30
ApiResult\$maxSize
$maxSize
Definition: ApiResult.php:143
ApiResult\setPreserveKeysList
static setPreserveKeysList(array &$arr, $names)
Preserve specified keys.
Definition: ApiResult.php:675
ApiResult\ADD_ON_TOP
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
ApiResult\getResultData
getResultData( $path=[], $transforms=[])
Get the result data array.
Definition: ApiResult.php:252
ApiResult\unsetSubelementsList
static unsetSubelementsList(array &$arr, $names)
Causes the elements with the specified names to be output as attributes (when possible) rather than a...
Definition: ApiResult.php:592
$path
$path
Definition: NoLocalSettings.php:26
as
This document is intended to provide useful advice for parties seeking to redistribute MediaWiki to end users It s targeted particularly at maintainers for Linux since it s been observed that distribution packages of MediaWiki often break We ve consistently had to recommend that users seeking support use official tarballs instead of their distribution s and this often solves whatever problem the user is having It would be nice if this could such as
Definition: distributors.txt:9
$keys
$keys
Definition: testCompression.php:65
ApiResult\OVERRIDE
const OVERRIDE
Override existing value in addValue(), setValue(), and similar functions.
Definition: ApiResult.php:39
ApiResult\formatExpiry
static formatExpiry( $expiry, $infinity='infinity')
Format an expiry timestamp for API output.
Definition: ApiResult.php:1207
ApiResult\META_KVP_MERGE
const META_KVP_MERGE
Key for the metadata item that indicates that the KVP key should be added into an assoc value,...
Definition: ApiResult.php:127
ApiResult\$data
$data
Definition: ApiResult.php:143
ApiResult\setIndexedTagNameRecursive
static setIndexedTagNameRecursive(array &$arr, $tag)
Set indexed tag name on $arr and all subarrays.
Definition: ApiResult.php:641
ApiResult\stripMetadata
static stripMetadata( $data)
Recursively remove metadata keys from a data array or object.
Definition: ApiResult.php:1024
ApiResult\META_CONTENT
const META_CONTENT
Key for the 'content' metadata item.
Definition: ApiResult.php:88
ApiResult\setSubelementsList
static setSubelementsList(array &$arr, $names)
Causes the elements with the specified names to be output as subelements rather than attributes.
Definition: ApiResult.php:565
$flags
it s the revision text itself In either if gzip is the revision text is gzipped $flags
Definition: hooks.txt:2749
data
and how to run hooks for an and one after Each event has a preferably in CamelCase For ArticleDelete hook A clump of code and data that should be run when an event happens This can be either a function and a chunk of data
Definition: hooks.txt:6
array
the array() calling protocol came about after MediaWiki 1.4rc1.
$wgContLang
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 content language as $wgContLang
Definition: design.txt:56
ApiResult\addIndexedTagNameRecursive
addIndexedTagNameRecursive( $path, $tag)
Set indexed tag name on $path and all subarrays.
Definition: ApiResult.php:660