* This is a value object for authentication requests.
*
* An AuthenticationRequest represents a set of form fields that are needed on
- * and provided from the login, account creation, or password change forms.
+ * and provided from a login, account creation, password change or similar form.
*
* @ingroup Auth
* @since 1.27
/** Indicates that the request is not required for authentication to proceed. */
const OPTIONAL = 0;
- /** Indicates that the request is required for authentication to proceed. */
+ /** Indicates that the request is required for authentication to proceed.
+ * This will only be used for UI purposes; it is the authentication providers'
+ * responsibility to verify that all required requests are present.
+ */
const REQUIRED = 1;
/** Indicates that the request is required by a primary authentication
- * provdier, but other primary authentication providers do not require it. */
+ * provider. Since the user can choose which primary to authenticate with,
+ * the request might or might not end up being actually required. */
const PRIMARY_REQUIRED = 2;
/** @var string|null The AuthManager::ACTION_* constant this request was
/** @var string|null Return-to URL, in case of redirect */
public $returnToUrl = null;
- /** @var string|null Username. May not be used by all subclasses. */
+ /** @var string|null Username. See AuthenticationProvider::getAuthenticationRequests()
+ * for details of what this means and how it behaves. */
public $username = null;
/**
* - label: (Message) Text suitable for a label in an HTML form
* - help: (Message) Text suitable as a description of what the field is
* - optional: (bool) If set and truthy, the field may be left empty
+ * - sensitive: (bool) If set and truthy, the field is considered sensitive. Code using the
+ * request should avoid exposing the value of the field.
+ *
+ * All AuthenticationRequests are populated from the same data, so most of the time you'll
+ * want to prefix fields names with something unique to the extension/provider (although
+ * in some cases sharing the field with other requests is the right thing to do, e.g. for
+ * a 'password' field).
*
* @return array As above
*/
/**
* Initialize form submitted form data.
*
- * Should always return false if self::getFieldInfo() returns an empty
- * array.
+ * The default behavior is to to check for each key of self::getFieldInfo()
+ * in the submitted data, and copy the value - after type-appropriate transformations -
+ * to $this->$key. Most subclasses won't need to override this; if you do override it,
+ * make sure to always return false if self::getFieldInfo() returns an empty array.
*
- * @param array $data Submitted data as an associative array
+ * @param array $data Submitted data as an associative array (keys will correspond
+ * to getFieldInfo())
* @return bool Whether the request data was successfully loaded
*/
public function loadFromSubmission( array $data ) {
*
* Only considers requests that have a "username" field.
*
- * @param AuthenticationRequest[] $requests
+ * @param AuthenticationRequest[] $reqs
* @return string|null
* @throws \UnexpectedValueException If multiple different usernames are present.
*/
$options['optional'] = !empty( $options['optional'] );
}
+ $options['sensitive'] = !empty( $options['sensitive'] );
+
if ( !array_key_exists( $name, $merged ) ) {
$merged[$name] = $options;
} elseif ( $merged[$name]['type'] !== $options['type'] ) {
}
$merged[$name]['optional'] = $merged[$name]['optional'] && $options['optional'];
+ $merged[$name]['sensitive'] = $merged[$name]['sensitive'] || $options['sensitive'];
// No way to merge 'value', 'image', 'help', or 'label', so just use
// the value from the first request.