MediaWiki  master
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 ) {
290  if ( ( $flags & self::NO_VALIDATE ) !== self::NO_VALIDATE ) {
291  $value = self::validateValue( $value );
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 ) {
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 & 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.
411  $value = self::validateValue( $value );
412  $flags |= self::NO_VALIDATE;
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  }
542  $arr[self::META_CONTENT] = $name;
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 ) ) {
648  self::setIndexedTagNameRecursive( $v, $tag );
649  }
650  }
651  }
652 
660  public function addIndexedTagNameRecursive( $path, $tag ) {
661  $arr = &$this->path( $path );
662  self::setIndexedTagNameRecursive( $arr, $tag );
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 
& path($path, $create= 'append')
Return a reference to the internal data at $path.
Definition: ApiResult.php:1115
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
wfGetDB($db, $groups=[], $wiki=false)
Get a Database object.
the array() calling protocol came about after MediaWiki 1.4rc1.
Formats errors and warnings for the API, and add them to the associated ApiResult.
setErrorFormatter(ApiErrorFormatter $formatter)
Set the error formatter.
Definition: ApiResult.php:171
magic word the default is to use $key to get the and $key value or $key value text $key value html to format the value $key
Definition: hooks.txt:2610
addSubelementsList($path, $names)
Causes the elements with the specified names to be output as subelements rather than attributes...
Definition: ApiResult.php:580
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
$mainForContinuation
Definition: ApiResult.php:147
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:2019
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:175
$value
const META_TYPE
Key for the 'type' metadata item.
Definition: ApiResult.php:108
removeValue($path, $name, $flags=0)
Remove value from the output data at the given path.
Definition: ApiResult.php:453
getSize()
Get the size of the result, i.e.
Definition: ApiResult.php:273
const META_PRESERVE_KEYS
Key for the 'preserve keys' metadata item.
Definition: ApiResult.php:82
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
when a variable name is used in a it is silently declared as a new local masking the global
Definition: design.txt:93
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
static setIndexedTagName(array &$arr, $tag)
Set the tag name for numeric-keyed values in XML format.
Definition: ApiResult.php:616
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
static size($value)
Get the 'real' size of a result item.
Definition: ApiResult.php:1089
addParsedLimit($moduleName, $limit)
Add the numeric limit for a limit=max to the result.
Definition: ApiResult.php:511
$last
wfTimestamp($outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
serializeForApiResult()
Allow for adding one ApiResult into another.
Definition: ApiResult.php:180
static unsetValue(array &$arr, $name)
Remove an output value to the array by name.
Definition: ApiResult.php:434
addIndexedTagName($path, $tag)
Set the tag name for numeric-keyed values in XML format.
Definition: ApiResult.php:629
addValue($path, $name, $value, $flags=0)
Add value to the output data at the given path.
Definition: ApiResult.php:405
addPreserveKeysList($path, $names)
Preserve specified keys.
Definition: ApiResult.php:690
static stripMetadata($data)
Recursively remove metadata keys from a data array or object.
Definition: ApiResult.php:1024
static setArrayTypeRecursive(array &$arr, $type, $kvpKeyName=null)
Set the array data type recursively.
Definition: ApiResult.php:759
static validateValue($value)
Validate a value for addition to the result.
Definition: ApiResult.php:332
This is the main API class, used for both external and internal processing.
Definition: ApiMain.php:43
static applyTransformations(array $dataIn, array $transforms)
Apply transformations to an array, returning the transformed array.
Definition: ApiResult.php:806
wfIsInfinity($str)
Determine input string is represents as infinity.
wfDeprecated($function, $version=false, $component=false, $callerOffset=2)
Throws a warning that $function is deprecated.
static stripMetadataNonRecursive($data, &$metadata=null)
Remove metadata keys from a data array or object, non-recursive.
Definition: ApiResult.php:1058
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
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
This interface allows for overriding the default conversion applied by ApiResult::validateValue().
This class represents the result of the API operations.
Definition: ApiResult.php:33
const NO_VALIDATE
For addValue(), setValue() and similar functions, do not validate data.
Definition: ApiResult.php:64
static formatExpiry($expiry, $infinity= 'infinity')
Format an expiry timestamp for API output.
Definition: ApiResult.php:1207
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
static setSubelementsList(array &$arr, $names)
Causes the elements with the specified names to be output as subelements rather than attributes...
Definition: ApiResult.php:565
static setIndexedTagNameRecursive(array &$arr, $tag)
Set indexed tag name on $arr and all subarrays.
Definition: ApiResult.php:641
static unsetPreserveKeysList(array &$arr, $names)
Don't preserve specified keys.
Definition: ApiResult.php:702
addArrayType($path, $tag, $kvpKeyName=null)
Set the array data type for a path.
Definition: ApiResult.php:747
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
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
removeSubelementsList($path, $names)
Causes the elements with the specified names to be output as attributes (when possible) rather than a...
Definition: ApiResult.php:605
const META_INDEXED_TAG_NAME
Key for the 'indexed tag name' metadata item.
Definition: ApiResult.php:70
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
static setValue(array &$arr, $name, $value, $flags=0)
Add an output value to the array by name.
Definition: ApiResult.php:289
const META_SUBELEMENTS
Key for the 'subelements' metadata item.
Definition: ApiResult.php:76
reset()
Clear the current result data.
Definition: ApiResult.php:192
static numParam($num)
Definition: Message.php:1028
removePreserveKeysList($path, $names)
Don't preserve specified keys.
Definition: ApiResult.php:715
addContentField($path, $name, $flags=0)
Set the name of the content field name (META_CONTENT)
Definition: ApiResult.php:553
const META_BC_BOOLS
Key for the 'BC bools' metadata item.
Definition: ApiResult.php:134
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:56
addArrayTypeRecursive($path, $tag, $kvpKeyName=null)
Set the array data type for a path recursively.
Definition: ApiResult.php:775
Allows to change the fields on the form that will be generated $name
Definition: hooks.txt:302
addIndexedTagNameRecursive($path, $tag)
Set indexed tag name on $path and all subarrays.
Definition: ApiResult.php:660
static setPreserveKeysList(array &$arr, $names)
Preserve specified keys.
Definition: ApiResult.php:675
static setContentField(array &$arr, $name, $flags=0)
Set the name of the content field name (META_CONTENT)
Definition: ApiResult.php:532
const META_CONTENT
Key for the 'content' metadata item.
Definition: ApiResult.php:88
const DB_REPLICA
Definition: defines.php:25
static setArrayType(array &$arr, $type, $kvpKeyName=null)
Set the array data type.
Definition: ApiResult.php:728
const META_BC_SUBELEMENTS
Key for the 'BC subelements' metadata item.
Definition: ApiResult.php:141
const OVERRIDE
Override existing value in addValue(), setValue(), and similar functions.
Definition: ApiResult.php:39
getResultData($path=[], $transforms=[])
Get the result data array.
Definition: ApiResult.php:252
static configuration should be added through ResourceLoaderGetConfigVars instead & $vars
Definition: hooks.txt:2252
__construct($maxSize)
Definition: ApiResult.php:153
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
static isMetadataKey($key)
Test whether a key should be considered metadata.
Definition: ApiResult.php:793