X-Git-Url: https://git.heureux-cyclage.org/?a=blobdiff_plain;f=includes%2Fauth%2FAuthenticationRequest.php;h=7fc362a2042722c1393e7cc4c163425a9145b4bf;hb=5473e9e9eeea71b0a32b2b0e703529e196721407;hp=2474b8b8300713d52419002fc699ef31b38ba69e;hpb=e14ac4bcb8136332694ce417213b2a6099c44c6f;p=lhc%2Fweb%2Fwiklou.git

diff --git a/includes/auth/AuthenticationRequest.php b/includes/auth/AuthenticationRequest.php
index 2474b8b830..7fc362a204 100644
--- a/includes/auth/AuthenticationRequest.php
+++ b/includes/auth/AuthenticationRequest.php
@@ -29,7 +29,7 @@ use Message;
  * 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
@@ -39,11 +39,14 @@ abstract class AuthenticationRequest {
 	/** 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. Since the user can choose which primary to authenticate with,
+	 * 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;
 
@@ -60,7 +63,8 @@ abstract class AuthenticationRequest {
 	/** @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;
 
 	/**
@@ -104,6 +108,15 @@ abstract class AuthenticationRequest {
 	 *  - 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.
+	 *  - skippable: (bool) If set and truthy, the client is free to hide this
+	 *      field from the user to streamline the workflow. If all fields are
+	 *      skippable (except possibly a single button), no user interaction is
+	 *      required at all.
+	 *
+	 * 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
 	 */
@@ -126,10 +139,13 @@ abstract class AuthenticationRequest {
 	/**
 	 * 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 ) {
@@ -250,7 +266,7 @@ abstract class AuthenticationRequest {
 	 *
 	 * 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.
 	 */