Merge branch 'feature/16-rename-username-to-identity' into release-1.0.0

Forward port #16

Conflicts:
	CHANGELOG.md

Author: weierophinney

CHANGELOG.md

@@ -26,15 +26,17 @@ All notable changes to this project will be documented in this file, in reverse
 
 - Nothing.
 
-## 0.2.1 - TBD
+## 0.3.0 - 2018-01-24
 
 ### Added
 
 - Nothing.
 
 ### Changed
 
-- Nothing
+- [#14](https://github.com/zendframework/zend-expressive-authentication/issues/14)
+  renames the method `UserInterface::getUsername()` to
+  `UserInterface::getIdentity()`.
 
 ### Deprecated
 

docs/book/v1/intro.md

@@ -22,11 +22,11 @@ namespace Zend\Expressive\Authentication;
 interface UserInterface
 {
     /**
-     * Get the username
+     * Get the unique user identity (id, username, email address or ...)
      *
      * @return string
      */
-    public function getUsername(): string;
+    public function getIdentity(): string;
 
     /**
      * Get all user roles
@@ -40,7 +40,7 @@ interface UserInterface
 The `UserInterface` attribute in the PSR-7 request can be used for checking
 if a user has been authenticated or not, e.g. it can be used to verify the
 authorization level of a user (for this scope, it is consumed by
-[zend-expressive-authotization](https://github.com/zendframework/zend-expressive-authorization)).
+[zend-expressive-authorization](https://github.com/zendframework/zend-expressive-authorization)).
 
 ## Usage in the route
 

docs/book/v1/user-repository.md

@@ -42,3 +42,82 @@ result will be a `UserInterface` instance, otherwise a null value is returned.
 The second function is `getRolesFromUser()` 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.
+
+
+## Configure the user repository
+
+In order to use a user repository adapter, we need to configure it. For instance,
+to consume an `htpasswd` file, we need to configure the path to the file.
+Such configuration is provided in the `authentication` hierarchy provided to
+your [PSR-11](http://www.php-fig.org/psr/psr-11/) container. We demonstrate
+examples of such configuration below.
+
+Using [Expressive](https://docs.zendframework.com/zend-expressive/), this
+configuration can be stored in a file under the `/config/autoload/` folder.  We
+suggest to use a `.local.php` suffix — e.g.
+`/config/autoload/auth.local.php` — as local configuration is not stored
+in the version control system.
+
+You can also provide this configuration using a [ConfigProvider.php](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/ConfigProvider.php)
+class. [Read this blog post](https://framework.zend.com/blog/2017-04-20-config-aggregator.html)
+for more information on config providers.
+
+## htpasswd configuration
+
+When using the htpasswd user repository implementation, you need only configure
+the path to the `htpasswd` file:
+
+```php
+return [
+    'authentication' => [
+        'htpasswd' => 'insert the path to htpasswd file',
+    ],
+];
+```
+
+## PDO configuration
+
+When using the PDO user repository adapter, you will need to provide PDO
+connection parameters, as well as information on the table, field names, and a
+SQL statement for retrieiving user roles:
+
+```php
+return [
+    'authentication' => [
+        'pdo' => [
+            'dsn' => '',
+            'username' => '',
+            'password' => '',
+            'table' => 'user table name',
+            'field' => [
+                'identity' => 'identity field name',
+                'password' => 'password field name',
+            ],
+            'sql_get_roles' => 'SQL to retrieve roles with :identity parameter',
+        ],
+    ],
+];
+```
+
+The required parameters are `dsn`, `table`, and `field`.
+
+The `dsn` value is the DSN connection string to be used to connect to the database.
+For instance, using a SQLite database, a typical value is `sqlite:/path/to/file`.
+
+The `username` and `password` parameters are optional parameters used to connect
+to the database. Depending on the database, these parameters may not be required;
+e.g. [SQLite](https://sqlite.org/) does not require them.
+
+The `table` value is the name of the table containing the user credentials.
+
+The `field` parameter contains the field name of the `identity` of the user and
+the user `password.` The `identity` of the user can be a username, an email, etc.
+
+The `sql_get_roles` setting is an optional parameter that contains the SQL query
+for retrieving the user roles. The identity value must be specified using the
+placeholder `:identity`. For instance, if a role is stored in a user table, a
+typical query might look like the following:
+
+```sql
+SELECT role FROM user WHERE username = :identity
+```

src/ConfigProvider.php

@@ -29,8 +29,19 @@ public function getAuthenticationConfig() : array
              *
              * Example: using htpasswd UserRepositoryInterface implementation:
              *
-             * 'user_register' => [
-             *     'htpasswd' => 'insert the path to htpasswd file'
+             * [
+             *     'htpasswd' => 'insert the path to htpasswd file',
+             *     'pdo' => [
+             *         'dsn' => 'DSN for connection',
+             *         'username' => 'username for database connection, if needed',
+             *         'password' => 'password for database connection, if needed',
+             *         'table' => 'user table name',
+             *         'field' => [
+             *             'identity' => 'identity field name',
+             *             'password' => 'password field name',
+             *         ],
+             *         'sql_get_roles' => 'SQL to retrieve roles by :identity',
+             *     ],
              * ]
              */
         ];

src/UserInterface.php

@@ -12,9 +12,9 @@
 interface UserInterface
 {
     /**
-     * Get the username
+     * Get the unique user identity (id, username, email address or ...)
      */
-    public function getUsername() : string;
+    public function getIdentity() : string;
 
     /**
      * Get all user roles

src/UserRepository/Htpasswd.php

@@ -70,7 +70,7 @@ public function authenticate(string $credential, string $password = null) : ?Use
     /**
      * {@inheritDoc}
      */
-    public function getRolesFromUser(string $username) : array
+    public function getRolesFromUser(string $identity) : array
     {
         return [];
     }

src/UserRepository/HtpasswdFactory.php

@@ -19,9 +19,7 @@ class HtpasswdFactory
      */
     public function __invoke(ContainerInterface $container) : Htpasswd
     {
-        $config = $container->has('config') ? $container->get('config') : [];
-        $htpasswd = $config['authentication']['htpasswd'] ?? null;
-
+        $htpasswd = $container->get('config')['authentication']['htpasswd'] ?? null;
         if (null === $htpasswd) {
             throw new Exception\InvalidConfigException(sprintf(
                 'Config key authentication.htpasswd is not present; cannot create %s user repository adapter',

src/UserRepository/PdoDatabase.php

@@ -10,6 +10,7 @@
 namespace Zend\Expressive\Authentication\UserRepository;
 
 use PDO;
+use PDOException;
 use Zend\Expressive\Authentication\Exception;
 use Zend\Expressive\Authentication\UserInterface;
 use Zend\Expressive\Authentication\UserRepositoryInterface;
@@ -44,14 +45,20 @@ public function __construct(PDO $pdo, array $config)
     public function authenticate(string $credential, string $password = null) : ?UserInterface
     {
         $sql = sprintf(
-            "SELECT %s FROM %s WHERE %s = :username",
+            "SELECT %s FROM %s WHERE %s = :identity",
             $this->config['field']['password'],
             $this->config['table'],
-            $this->config['field']['username']
+            $this->config['field']['identity']
         );
 
         $stmt = $this->pdo->prepare($sql);
-        $stmt->bindParam(':username', $credential);
+        if (false === $stmt) {
+            throw new Exception\RuntimeException(
+                'An error occurred when preparing to fetch user details from ' .
+                'the repository; please verify your configuration'
+            );
+        }
+        $stmt->bindParam(':identity', $credential);
         $stmt->execute();
 
         $result = $stmt->fetchObject();
@@ -67,20 +74,32 @@ public function authenticate(string $credential, string $password = null) : ?Use
     /**
      * {@inheritDoc}
      */
-    public function getRolesFromUser(string $username) : array
+    public function getRolesFromUser(string $identity) : array
     {
         if (! isset($this->config['sql_get_roles'])) {
             return [];
         }
 
-        if (false === strpos($this->config['sql_get_roles'], ':username')) {
+        if (false === strpos($this->config['sql_get_roles'], ':identity')) {
             throw new Exception\InvalidConfigException(
-                'The sql_get_roles configuration setting must include a :username parameter'
+                'The sql_get_roles configuration setting must include a :identity parameter'
             );
         }
 
-        $stmt = $this->pdo->prepare($this->config['sql_get_roles']);
-        $stmt->bindParam(':username', $username);
+        try {
+            $stmt = $this->pdo->prepare($this->config['sql_get_roles']);
+        } catch (PDOException $e) {
+            throw new Exception\RuntimeException(sprintf(
+                'Error preparing retrieval of user roles: %s',
+                $e->getMessage()
+            ));
+        }
+        if (false === $stmt) {
+            throw new Exception\RuntimeException(sprintf(
+                'Error preparing retrieval of user roles: unknown error'
+            ));
+        }
+        $stmt->bindParam(':identity', $identity);
 
         if (! $stmt->execute()) {
             return [];

src/UserRepository/PdoDatabaseFactory.php

@@ -36,9 +36,9 @@ public function __invoke(ContainerInterface $container) : PdoDatabase
                 'The PDO table name is missing in the configuration'
             );
         }
-        if (! isset($pdo['field']['username'])) {
+        if (! isset($pdo['field']['identity'])) {
             throw new Exception\InvalidConfigException(
-                'The PDO username field is missing in the configuration'
+                'The PDO identity field is missing in the configuration'
             );
         }
         if (! isset($pdo['field']['password'])) {

src/UserRepository/UserTrait.php

@@ -14,23 +14,23 @@
 trait UserTrait
 {
     /**
-     * Generate a user from username and list of roles
+     * Generate a user from identity and list of roles
      */
-    protected function generateUser(string $username, ?array $roles = null) : UserInterface
+    protected function generateUser(string $identity, ?array $roles = null) : UserInterface
     {
-        return new class($username, $roles) implements UserInterface {
-            private $username;
+        return new class($identity, $roles) implements UserInterface {
+            private $identity;
             private $roles;
 
-            public function __construct(string $username, $roles)
+            public function __construct(string $identity, $roles)
             {
-                $this->username = $username;
+                $this->identity = $identity;
                 $this->roles = $roles ?: [];
             }
 
-            public function getUsername() : string
+            public function getIdentity() : string
             {
-                return $this->username;
+                return $this->identity;
             }
 
             public function getUserRoles() : array