Provide type-safety for user factories

Wraps `$userFactory` constructor arguments in a callable that provides a
return type hint, as well as type hints and optional arguments for all
parameters.

Author: weierophinney

src/DefaultUser.php

@@ -9,12 +9,29 @@
 
 namespace Zend\Expressive\Authentication;
 
+/**
+ * Default implementation of UserInterface.
+ *
+ * This implementation is modeled as immutable, to prevent propagation of
+ * user state changes.
+ *
+ * We recommend that any details injected are serializable.
+ */
 final class DefaultUser implements UserInterface
 {
+    /**
+     * @var string
+     */
     private $identity;
 
+    /**
+     * @var string[]
+     */
     private $roles;
 
+    /**
+     * @var array
+     */
     private $details;
 
     public function __construct(string $identity, array $roles = [], array $details = [])
@@ -39,6 +56,11 @@ public function getDetails() : array
         return $this->details;
     }
 
+    /**
+     * @param mixed $default Default value to return if no detail matching
+     *     $name is discovered.
+     * @return mixed
+     */
     public function getDetail(string $name, $default = null)
     {
         return $this->details[$name] ?? $default;

src/DefaultUserFactory.php

@@ -1,7 +1,7 @@
 <?php
 /**
  * @see       https://github.com/zendframework/zend-expressive-authentication for the canonical source repository
- * @copyright Copyright (c) 2017 Zend Technologies USA Inc. (https://www.zend.com)
+ * @copyright Copyright (c) 2018 Zend Technologies USA Inc. (https://www.zend.com)
  * @license   https://github.com/zendframework/zend-expressive-authentication/blob/master/LICENSE.md New BSD License
  */
 
@@ -11,11 +11,16 @@
 
 use Psr\Container\ContainerInterface;
 
+/**
+ * Produces a callable factory capable of itself producing a UserInterface
+ * instance; this approach is used to allow substituting alternative user
+ * implementations without requiring extensions to existing repositories.
+ */
 class DefaultUserFactory
 {
     public function __invoke(ContainerInterface $container) : callable
     {
-        return function (string $identity, array $roles = [], array $details = []) {
+        return function (string $identity, array $roles = [], array $details = []) : UserInterface {
             return new DefaultUser($identity, $roles, $details);
         };
     }

src/UserInterface.php

@@ -1,7 +1,7 @@
 <?php
 /**
  * @see       https://github.com/zendframework/zend-expressive-authentication for the canonical source repository
- * @copyright Copyright (c) 2017 Zend Technologies USA Inc. (https://www.zend.com)
+ * @copyright Copyright (c) 2017-2018 Zend Technologies USA Inc. (https://www.zend.com)
  * @license   https://github.com/zendframework/zend-expressive-authentication/blob/master/LICENSE.md New BSD License
  */
 

src/UserRepository/Htpasswd.php

@@ -1,7 +1,7 @@
 <?php
 /**
  * @see       https://github.com/zendframework/zend-expressive-authentication for the canonical source repository
- * @copyright Copyright (c) 2017 Zend Technologies USA Inc. (https://www.zend.com)
+ * @copyright Copyright (c) 2017-2018 Zend Technologies USA Inc. (https://www.zend.com)
  * @license   https://github.com/zendframework/zend-expressive-authentication/blob/master/LICENSE.md New BSD License
  */
 
@@ -42,7 +42,15 @@ public function __construct(string $filename, callable $userFactory)
             ));
         }
         $this->filename = $filename;
-        $this->userFactory = $userFactory;
+
+        // Provide type safety for the composed user factory.
+        $this->userFactory = function (
+            string $identity,
+            array $roles = [],
+            array $details = []
+        ) use ($userFactory) : UserInterface {
+            return $userFactory($identity, $roles, $details);
+        };
     }
 
     /**

src/UserRepository/PdoDatabase.php

@@ -1,7 +1,7 @@
 <?php
 /**
  * @see       https://github.com/zendframework/zend-expressive-authentication for the canonical source repository
- * @copyright Copyright (c) 2017 Zend Technologies USA Inc. (https://www.zend.com)
+ * @copyright Copyright (c) 2017-2018 Zend Technologies USA Inc. (https://www.zend.com)
  * @license   https://github.com/zendframework/zend-expressive-authentication/blob/master/LICENSE.md New BSD License
  */
 
@@ -17,7 +17,8 @@
 
 /**
  * Adapter for PDO database
- * It supports only bcrypt hash password for security reason
+ *
+ * It supports only bcrypt password hashing for security reasons.
  */
 class PdoDatabase implements UserRepositoryInterface
 {
@@ -43,7 +44,15 @@ public function __construct(
     ) {
         $this->pdo = $pdo;
         $this->config = $config;
-        $this->userFactory = $userFactory;
+
+        // Provide type safety for the composed user factory.
+        $this->userFactory = function (
+            string $identity,
+            array $roles = [],
+            array $details = []
+        ) use ($userFactory) : UserInterface {
+            return $userFactory($identity, $roles, $details);
+        };
     }
 
     /**
@@ -97,7 +106,7 @@ protected function getUserRoles(string $identity) : array
 
         if (false === strpos($this->config['sql_get_roles'], ':identity')) {
             throw new Exception\InvalidConfigException(
-                'The sql_get_roles configuration setting must include a :identity parameter'
+                'The sql_get_roles configuration setting must include an :identity parameter'
             );
         }