Normalization of user attributes added to Auth Client.

extensions/yii/authclient/ClientTrait.php

@@ -12,27 +12,35 @@ use yii\base\NotSupportedException;
 use yii\helpers\StringHelper;
 
 /**
- * Class ProviderTrait
+ * ProviderTrait can be used to satisfy [[ClientInterface]] interface.
  *
  * @see ClientInterface
  *
+ * @property string $id auth service id.
+ * @property string $name auth service name.
+ * @property string $title auth service title.
+ * @property array $userAttributes authenticated user attributes.
+ * @property array $normalizeUserAttributeMap map used to normalize user attributes fetched from
+ * external auth service in format: rawAttributeName => normalizedAttributeName.
+ * @property array $viewOptions view options in format: optionName => optionValue.
+ *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 2.0
  */
 trait ClientTrait
 {
 	/**
-	 * @var string service id.
+	 * @var string auth service id.
 	 * This value mainly used as HTTP request parameter.
 	 */
 	private $_id;
 	/**
-	 * @var string service unique name.
+	 * @var string auth service name.
 	 * This value may be used in database records, CSS files and so on.
 	 */
 	private $_name;
 	/**
-	 * @var string service title to display in views.
+	 * @var string auth service title to display in views.
 	 */
 	private $_title;
 	/**
@@ -40,6 +48,11 @@ trait ClientTrait
 	 */
 	private $_userAttributes;
 	/**
+	 * @var array map used to normalize user attributes fetched from external auth service
+	 * in format: rawAttributeName => normalizedAttributeName
+	 */
+	private $_normalizeUserAttributeMap;
+	/**
 	 * @var array view options in format: optionName => optionValue
 	 */
 	private $_viewOptions;
@@ -64,6 +77,14 @@ trait ClientTrait
 	}
 
 	/**
+	 * @param string $name service name.
+	 */
+	public function setName($name)
+	{
+		$this->_name = $name;
+	}
+
+	/**
 	 * @return string service name.
 	 */
 	public function getName()
@@ -75,11 +96,11 @@ trait ClientTrait
 	}
 
 	/**
-	 * @param string $name service name.
+	 * @param string $title service title.
 	 */
-	public function setName($name)
+	public function setTitle($title)
 	{
-		$this->_name = $name;
+		$this->_title = $title;
 	}
 
 	/**
@@ -94,11 +115,11 @@ trait ClientTrait
 	}
 
 	/**
-	 * @param string $title service title.
+	 * @param array $userAttributes list of user attributes
 	 */
-	public function setTitle($title)
+	public function setUserAttributes($userAttributes)
 	{
-		$this->_title = $title;
+		$this->_userAttributes = $this->normalizeUserAttributes($userAttributes);
 	}
 
 	/**
@@ -107,17 +128,28 @@ trait ClientTrait
 	public function getUserAttributes()
 	{
 		if ($this->_userAttributes === null) {
-			$this->_userAttributes = $this->initUserAttributes();
+			$this->_userAttributes = $this->normalizeUserAttributes($this->initUserAttributes());
 		}
 		return $this->_userAttributes;
 	}
 
 	/**
-	 * @param array $userAttributes list of user attributes
+	 * @param array $normalizeUserAttributeMap normalize user attribute map.
 	 */
-	public function setUserAttributes($userAttributes)
+	public function setNormalizeUserAttributeMap($normalizeUserAttributeMap)
 	{
-		$this->_userAttributes = $userAttributes;
+		$this->_normalizeUserAttributeMap = $normalizeUserAttributeMap;
+	}
+
+	/**
+	 * @return array normalize user attribute map.
+	 */
+	public function getNormalizeUserAttributeMap()
+	{
+		if ($this->_normalizeUserAttributeMap === null) {
+			$this->_normalizeUserAttributeMap = $this->defaultNormalizeUserAttributeMap();
+		}
+		return $this->_normalizeUserAttributeMap;
 	}
 
 	/**
@@ -167,6 +199,16 @@ trait ClientTrait
 	}
 
 	/**
+	 * Returns the default [[normalizeUserAttributeMap]] value.
+	 * Particular client may override this method in order to provide specific default map.
+	 * @return array normalize attribute map.
+	 */
+	public function defaultNormalizeUserAttributeMap()
+	{
+		return [];
+	}
+
+	/**
 	 * Returns the default [[viewOptions]] value.
 	 * Particular client may override this method in order to provide specific default view options.
 	 * @return array list of default [[viewOptions]]
@@ -175,4 +217,19 @@ trait ClientTrait
 	{
 		return [];
 	}
+
+	/**
+	 * Normalize given user attributes according to {@link normalizeUserAttributeMap}.
+	 * @param array $attributes raw attributes.
+	 * @return array normalized attributes.
+	 */
+	protected function normalizeUserAttributes($attributes)
+	{
+		foreach ($this->getNormalizeUserAttributeMap() as $normalizedName => $actualName) {
+			if (array_key_exists($actualName, $attributes)) {
+				$attributes[$normalizedName] = $attributes[$actualName];
+			}
+		}
+		return $attributes;
+	}
 }

tests/unit/extensions/authclient/ClientTraitTest.php

@@ -8,22 +8,6 @@ use yii\base\Object;
 
 class ClientTraitTest extends TestCase
 {
-	protected function setUp()
-	{
-		$config = [
-			'components' => [
-				'user' => [
-					'identityClass' => '\yii\web\IdentityInterface'
-				],
-				'request' => [
-					'hostInfo' => 'http://testdomain.com',
-					'scriptUrl' => '/index.php',
-				],
-			]
-		];
-		$this->mockApplication($config, '\yii\web\Application');
-	}
-
 	public function testSetGet()
 	{
 		$client = new Client();
@@ -47,6 +31,13 @@ class ClientTraitTest extends TestCase
 		$client->setUserAttributes($userAttributes);
 		$this->assertEquals($userAttributes, $client->getUserAttributes(), 'Unable to setup user attributes!');
 
+		$normalizeUserAttributeMap = [
+			'name' => 'some/name',
+			'email' => 'some/email',
+		];
+		$client->setNormalizeUserAttributeMap($normalizeUserAttributeMap);
+		$this->assertEquals($normalizeUserAttributeMap, $client->getNormalizeUserAttributeMap(), 'Unable to setup normalize user attribute map!');
+
 		$viewOptions = [
 			'option1' => 'value1',
 			'option2' => 'value2',
@@ -57,11 +48,34 @@ class ClientTraitTest extends TestCase
 
 	public function testGetDefaults()
 	{
-		$provider = new Client();
+		$client = new Client();
+
+		$this->assertNotEmpty($client->getName(), 'Unable to get default name!');
+		$this->assertNotEmpty($client->getTitle(), 'Unable to get default title!');
+		$this->assertNotNull($client->getViewOptions(), 'Unable to get default view options!');
+		$this->assertNotNull($client->getNormalizeUserAttributeMap(), 'Unable to get default normalize user attribute map!');
+	}
+
+	/**
+	 * @depends testSetGet
+	 */
+	public function testNormalizeUserAttributes()
+	{
+		$client = new Client();
 
-		$this->assertNotEmpty($provider->getName(), 'Unable to get default name!');
+		$normalizeUserAttributeMap = [
-		$this->assertNotEmpty($provider->getTitle(), 'Unable to get default title!');
+			'raw/name' => 'name',
-		$this->assertNotNull($provider->getViewOptions(), 'Unable to get default view options!');
+			'raw/email' => 'email',
+		];
+		$client->setNormalizeUserAttributeMap($normalizeUserAttributeMap);
+		$rawUserAttributes = [
+			'raw/name' => 'name value',
+			'raw/email' => 'email value',
+		];
+		$client->setUserAttributes($rawUserAttributes);
+		$normalizedUserAttributes = $client->getUserAttributes();
+		$expectedNormalizedUserAttributes = array_combine(array_keys($normalizeUserAttributeMap), array_values($rawUserAttributes));
+		$this->assertEquals($expectedNormalizedUserAttributes, $normalizedUserAttributes);
 	}
 }