Changed the UserRepositoryInterface and refactored the user's factory

Author: ezimuel

docs/book/v1/intro.md

@@ -43,8 +43,10 @@ authorization level of a user (for this scope, it is consumed by
 ## Default User class
 
 We provide a default implementation of `UserInterface` via the class `Zend\Expressive\Authentication\DefaultUser`.
-This class is a basic implementation of `UserInterface`. This class is final and
-it's immutable, that means you cannot change it state at runtime.
+The class is final and immutable, in order to prevent runtime changes.
+We provide a factory class for generating `DefaultUser` instances via
+`Zend\Expressive\Authentication\DefaultUserFactory`.
+
 In order to set the identity and the user's role we provided a default factory
 class that generates a `UserInterface` object. This factory is
 `Zend\Expressive\Authentication\UserInterfaceFactory`. This class uses a `generate`
@@ -56,19 +58,16 @@ If you want, you can customize the `UserInterfaceFactory` using your custom
 follows:
 
 ```php
-// src/ConfigProvider.php
+return [
     // ...
-    public function getDependencies() : array
-    {
-        return [
+    'dependencies' => [
+        'factories' => [
             // ...
-            'factories' => [
-                // here change the UserInterfaceFactory::class with your class
-                UserInterface::class => UserInterfaceFactory::class
-            ]
-        ];
-    }
-    // ...
+            // change the DefaultUserFactory::class with your custom factory
+            UserInterface::class => DefaultUserFactory::class
+        ]
+    ]
+];
 ```
 
 ## Usage in the route
@@ -104,18 +103,16 @@ Basic Access Authentication* adapter and the *htpasswd* file as the user
 repository.
 
 ```php
-// src/ConfigProvider.php
+return [
     // ...
-    public function getDependencies() : array
-    {
-        return [
+    'dependencies' => [
+        // ...
+        'aliases' => [
             // ...
-            'aliases' => [
-                // ...
-                AuthenticationInterface::class => Basic\BasicAccess::class,
-                UserRepositoryInterface::class => UserRepository\Htpasswd::class
-            ]
-        ];
-    }
-    // ...
+            AuthenticationInterface::class => Basic\BasicAccess::class,
+            UserRepositoryInterface::class => UserRepository\Htpasswd::class
+        ]
+    ]
+];
+
 ```

docs/book/v1/user-repository.md

@@ -31,18 +31,30 @@ interface UserRepositoryInterface
      * @param string $username
      * @return string[]
      */
-    public function getRolesFromUser(string $username) : array;
+    public function getUserRoles(string $username) : array;
+
+    /**
+     * Get the user details if present.
+     *
+     * @param string $identity
+     * @return string[]
+     */
+    public function getUserDetails(string $identity) : array;
 }
 ```
 
-It contains two functions: `authenticate()` and `getRolesFromUser()`. The first
-is used to authenticate using the user's credential. If authenticated, the
-result will be a `UserInterface` instance, otherwise a null value is returned.
+It contains 3 functions: `authenticate()`, `getUserRoles()`, and `getUserDetails`.
+The first function is used to authenticate the user's credential. If
+authenticated, the result will be a `UserInterface` instance, otherwise a null
+value is returned.
 
-The second function is `getRolesFromUser()` and it specifies how to retrieve
+The second function is `getUserRoles()` and it specifies how to retrieve
 the roles for a user. If a user does not have roles, this function will return
 an empty array.
 
+The last function is `getUserDetails()` and it specifies the additional user
+information (details), if any.
+
 
 ## Configure the user repository
 
@@ -93,7 +105,8 @@ return [
                 'identity' => 'identity field name',
                 'password' => 'password field name',
             ],
-            'sql_get_roles' => 'SQL to retrieve roles with :identity parameter',
+            'sql_get_roles'   => 'SQL to retrieve roles with :identity parameter',
+            'sql_get_details' => 'SQL to retrieve user details by :identity'
         ],
     ],
 ];
@@ -121,3 +134,6 @@ typical query might look like the following:
 ```sql
 SELECT role FROM user WHERE username = :identity
 ```
+
+The `sql_get_details` parameter is similar to `sql_get_roles`, it specified the
+SQL query for retrieving the user's additional details, if any.

src/ConfigProvider.php

@@ -41,7 +41,8 @@ public function getAuthenticationConfig() : array
              *             'identity' => 'identity field name',
              *             'password' => 'password field name',
              *         ],
-             *         'sql_get_roles' => 'SQL to retrieve roles by :identity',
+             *         'sql_get_roles'   => 'SQL to retrieve user roles by :identity',
+             *         'sql_get_details' => 'SQL to retrieve user details by :identity'
              *     ],
              * ]
              */
@@ -64,7 +65,7 @@ public function getDependencies() : array
                 AuthenticationMiddleware::class => AuthenticationMiddlewareFactory::class,
                 UserRepository\Htpasswd::class => UserRepository\HtpasswdFactory::class,
                 UserRepository\PdoDatabase::class => UserRepository\PdoDatabaseFactory::class,
-                UserInterface::class => UserInterfaceFactory::class
+                UserInterface::class => DefaultUserFactory::class
             ]
         ];
     }

src/DefaultUser.php

@@ -15,10 +15,13 @@ final class DefaultUser implements UserInterface
 
     private $roles;
 
-    public function __construct(string $identity, array $roles = [])
+    private $details;
+
+    public function __construct(string $identity, array $roles = [], array $details = [])
     {
         $this->identity = $identity;
         $this->roles = $roles;
+        $this->details = $details;
     }
 
     public function getIdentity() : string
@@ -30,4 +33,14 @@ public function getRoles() : array
     {
         return $this->roles;
     }
+
+    public function getDetails() : array
+    {
+        return $this->details;
+    }
+
+    public function getDetail(string $name, $default = null)
+    {
+        return $this->details[$name] ?? $default;
+    }
 }

src/UserInterfaceFactory.php renamed to src/DefaultUserFactory.php

@@ -11,10 +11,12 @@
 
 use Psr\Container\ContainerInterface;
 
-class UserInterfaceFactory
+class DefaultUserFactory
 {
-    public function generate(string $identity, array $roles = []) : UserInterface
+    public function __invoke(ContainerInterface $container) : callable
     {
-        return new DefaultUser($identity, $roles);
+        return function (string $identity, array $roles = [], array $details = []) {
+            return new DefaultUser($identity, $roles, $details);
+        };
     }
 }

src/UserInterface.php

@@ -22,4 +22,14 @@ public function getIdentity() : string;
      * @return string[]
      */
     public function getRoles() : array;
+
+    /**
+     * Get a detail $name if present, $default otherwise
+     */
+    public function getDetail(string $name, $default = null);
+
+    /**
+     * Get all the details, if any
+     */
+    public function getDetails() : array;
 }

src/UserRepository/Htpasswd.php

@@ -11,7 +11,6 @@
 
 use Zend\Expressive\Authentication\Exception;
 use Zend\Expressive\Authentication\UserInterface;
-use Zend\Expressive\Authentication\UserInterfaceFactory;
 use Zend\Expressive\Authentication\UserRepositoryInterface;
 
 /**
@@ -27,14 +26,14 @@ class Htpasswd implements UserRepositoryInterface
     private $filename;
 
     /**
-     * @var UserInterfaceFactory
+     * @var callable
      */
     private $userFactory;
 
     /**
      * @throws Exception\InvalidConfigException
      */
-    public function __construct(string $filename, UserInterfaceFactory $userFactory)
+    public function __construct(string $filename, callable $userFactory)
     {
         if (! file_exists($filename)) {
             throw new Exception\InvalidConfigException(sprintf(
@@ -67,15 +66,23 @@ public function authenticate(string $credential, string $password = null) : ?Use
         fclose($handle);
 
         if ($found && password_verify($password ?? '', $hash)) {
-            return $this->userFactory->generate($credential, $this->getRolesFromUser($credential));
+            return ($this->userFactory)($credential);
         }
         return null;
     }
 
     /**
      * {@inheritDoc}
      */
-    public function getRolesFromUser(string $identity) : array
+    public function getUserRoles(string $identity) : array
+    {
+        return [];
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getUserDetails(string $identity) : array
     {
         return [];
     }

src/UserRepository/PdoDatabase.php

@@ -13,7 +13,6 @@
 use PDOException;
 use Zend\Expressive\Authentication\Exception;
 use Zend\Expressive\Authentication\UserInterface;
-use Zend\Expressive\Authentication\UserInterfaceFactory;
 use Zend\Expressive\Authentication\UserRepositoryInterface;
 
 /**
@@ -33,14 +32,14 @@ class PdoDatabase implements UserRepositoryInterface
     private $config;
 
     /**
-     * @var UserInterfaceFactory
+     * @var callable
      */
     private $userFactory;
 
     public function __construct(
         PDO $pdo,
         array $config,
-        UserInterfaceFactory $userFactory
+        callable $userFactory
     ) {
         $this->pdo = $pdo;
         $this->config = $config;
@@ -75,9 +74,10 @@ public function authenticate(string $credential, string $password = null) : ?Use
         }
 
         if (password_verify($password, $result->{$this->config['field']['password']})) {
-            return $this->userFactory->generate(
+            return ($this->userFactory)(
                 $credential,
-                $this->getRolesFromUser($credential)
+                $this->getUserRoles($credential),
+                $this->getUserDetails($credential)
             );
         }
         return null;
@@ -86,7 +86,7 @@ public function authenticate(string $credential, string $password = null) : ?Use
     /**
      * {@inheritDoc}
      */
-    public function getRolesFromUser(string $identity) : array
+    public function getUserRoles(string $identity) : array
     {
         if (! isset($this->config['sql_get_roles'])) {
             return [];
@@ -123,4 +123,42 @@ public function getRolesFromUser(string $identity) : array
         }
         return $roles;
     }
+
+    public function getUserDetails(string $identity) : array
+    {
+        if (! isset($this->config['sql_get_details'])) {
+            return [];
+        }
+
+        if (false === strpos($this->config['sql_get_details'], ':identity')) {
+            throw new Exception\InvalidConfigException(
+                'The sql_get_details configuration setting must include a :identity parameter'
+            );
+        }
+
+        try {
+            $stmt = $this->pdo->prepare($this->config['sql_get_details']);
+        } catch (PDOException $e) {
+            throw new Exception\RuntimeException(sprintf(
+                'Error preparing retrieval of user details: %s',
+                $e->getMessage()
+            ));
+        }
+        if (false === $stmt) {
+            throw new Exception\RuntimeException(sprintf(
+                'Error preparing retrieval of user details: unknown error'
+            ));
+        }
+        $stmt->bindParam(':identity', $identity);
+
+        if (! $stmt->execute()) {
+            return [];
+        }
+
+        $details = [];
+        foreach ($stmt->fetchAll(PDO::FETCH_NUM) as $detail) {
+            $details[] = $detail[0];
+        }
+        return $details;
+    }
 }

src/UserRepositoryInterface.php

@@ -26,5 +26,13 @@ public function authenticate(string $credential, string $password = null) : ?Use
      * @param string $identity
      * @return string[]
      */
-    public function getRolesFromUser(string $identity) : array;
+    public function getUserRoles(string $identity) : array;
+
+    /**
+     * Get the user details if present.
+     *
+     * @param string $identity
+     * @return string[]
+     */
+    public function getUserDetails(string $identity) : array;
 }