Thijs/wiki.techinc.nl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

WebRequest: Document getVal caveat and recommend getText or getRawVal

Browse source 
Prior art in I8ce1fa31f, Id37619cead, I9db7b3f36f, If219463d80a.

Start to nudge future development in a better direction by starting
to discourage getVal() since it is an odd hybrid after all, that
for the most part could probably be replaced by getRawVal, except
that there is a handful of really critical getVal() calls for
"title" in many places that are difficult to track down, so for now
we're probably stuck with this.

Change-Id: I18767cd809f67bde6784bda5e3c85974ea2e7205
This commit is contained in:
Timo Tijhof 2021-08-10 22:36:25 +01:00 committed by Krinkle
parent 3c5ef86bc0
commit bd195f708f
1 changed files with 42 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
includes/WebRequest.php
View file

@ -464,16 +464,16 @@ class WebRequest {
}
/**
* Fetch a scalar from the input without normalization, or return $default
* if it's not set.
* Fetch a string WITHOUT any Unicode or line break normalization. This is a fast alternative
* for values that are known to be simple, e.g. pure ASCII. When reading user input, use
* {@see getText} instead.
*
* Unlike self::getVal(), this does not perform any normalization on the
* input value.
* Array values are discarded for security reasons. Use {@see getArray} or {@see getIntArray}.
*
* @since 1.28
* @param string $name
* @param string|null $default
* @return string|null
* @return string|null The value, or $default if none set
*/
public function getRawVal( $name, $default = null ) {
$name = strtr( $name, '.', '_' ); // See comment in self::getGPCVal()
@ -482,33 +482,54 @@ class WebRequest {
} else {
$val = $default;
}
if ( $val === null ) {
return $val;
} else {
return (string)$val;
}
return $val === null ? null : (string)$val;
}
/**
* Fetch a scalar from the input or return $default if it's not set.
* Returns a string. Arrays are discarded. Useful for
* non-freeform text inputs (e.g. predefined internal text keys
* selected by a drop-down menu). For freeform input, see getText().
* Fetch a text string and partially normalized it.
*
* Use of this method is discouraged. It doesn't normalize line breaks and defaults to null
* instead of the empty string. Instead:
* - Use {@see getText} when reading user input or form fields that are expected to contain
* non-ASCII characters.
* - Use {@see getRawVal} when reading ASCII strings, such as parameters used to select
* predefined behaviour in the software.
*
* Array values are discarded for security reasons. Use {@see getArray} or {@see getIntArray}.
*
* @param string $name
* @param string|null $default Optional default (or null)
* @return string|null
* @param string|null $default
* @return string|null The input value, or $default if none set
*/
public function getVal( $name, $default = null ) {
$val = $this->getGPCVal( $this->data, $name, $default );
if ( is_array( $val ) ) {
$val = $default;
}
if ( $val === null ) {
return $val;
} else {
return (string)$val;
}
return $val === null ? null : (string)$val;
}
/**
* Fetch a text string and return it in normalized form.
*
* This normalizes Unicode sequences (via {@see getGPCVal}) and line breaks.
*
* This should be used for all user input and form fields that are expected to contain non-ASCII
* characters, especially if the value will be stored or compared against stored values. Without
* normalization, logically identically values might not match when they are typed on different
* OS' or keyboards.
*
* Array values are discarded for security reasons. Use {@see getArray} or {@see getIntArray}.
*
* @param string $name
* @param string $default
* @return string The normalized input value, or $default if none set
*/
public function getText( $name, $default = '' ) {
$val = $this->getVal( $name, $default );
return str_replace( "\r\n", "\n", $val );
}
/**
@ -659,21 +680,6 @@ class WebRequest {
return $this->getRawVal( $name, null ) !== null;
}
/**
* Fetch a text string from the given array or return $default if it's not
* set. Carriage returns are stripped from the text. This should generally
* be used for form "<textarea>" and "<input>" fields, and for
* user-supplied freeform text input.
*
* @param string $name
* @param string $default Optional
* @return string
*/
public function getText( $name, $default = '' ) {
$val = $this->getVal( $name, $default );
return str_replace( "\r\n", "\n", $val );
}
/**
* Extracts the (given) named values into an array.
* No transformation is performed on the values.