Merge branch 'feature/16-rename-username-to-identity'

Close #16
Fixes #14

Author: weierophinney

CHANGELOG.md

@@ -2,15 +2,17 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 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

@@ -27,8 +27,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

@@ -9,9 +9,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

@@ -66,7 +66,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

@@ -17,9 +17,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

@@ -7,6 +7,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;
@@ -41,14 +42,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();
@@ -64,20 +71,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

@@ -34,9 +34,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

@@ -12,23 +12,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

src/UserRepositoryInterface.php

@@ -9,8 +9,8 @@
 interface UserRepositoryInterface
 {
     /**
-     * Authenticate the credential (username) using a password
-     * or using only the credential string (e.g. token based credential)
+     * Authenticate the identity (id, username, email ...) using a password
+     * or using only a credential string (e.g. token based credential)
      * It returns the authenticated user or null.
      *
      * @param string $credential can be also a token
@@ -20,8 +20,8 @@ public function authenticate(string $credential, string $password = null) : ?Use
     /**
      * Get the user roles if present.
      *
-     * @param string $username
+     * @param string $identity
      * @return string[]
      */
-    public function getRolesFromUser(string $username) : array;
+    public function getRolesFromUser(string $identity) : array;
 }

test/UserRepository/HtpasswdFactoryTest.php

@@ -22,16 +22,17 @@ protected function setUp()
 
     public function testInvokeWithMissingConfig()
     {
-        $this->container->has('config')->willReturn(false);
-        $this->container->get('config')->shouldNotBeCalled();
+        // We cannot throw a ContainerExceptionInterface directly; this
+        // approach simply mimics `get()` throwing _any_ exception, which is
+        // what will happen if `config` is not defined.
+        $this->container->get('config')->willThrow(new InvalidConfigException());
 
         $this->expectException(InvalidConfigException::class);
-        $htpasswd = ($this->factory)($this->container->reveal());
+        ($this->factory)($this->container->reveal());
     }
 
     public function testInvokeWithEmptyConfig()
     {
-        $this->container->has('config')->willReturn(true);
         $this->container->get('config')->willReturn([]);
 
         $this->expectException(InvalidConfigException::class);

test/UserRepository/HtpasswdTest.php

@@ -33,7 +33,7 @@ public function testAuthenticate()
 
         $user = $htpasswd->authenticate('test', 'password');
         $this->assertInstanceOf(UserInterface::class, $user);
-        $this->assertEquals('test', $user->getUsername());
+        $this->assertEquals('test', $user->getIdentity());
     }
 
     public function testAuthenticateInvalidUser()

test/UserRepository/PdoDatabaseFactoryTest.php

@@ -8,6 +8,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Psr\Container\ContainerInterface;
+use Zend\Expressive\Authentication\Exception\InvalidConfigException;
 use Zend\Expressive\Authentication\UserRepository\PdoDatabase;
 use Zend\Expressive\Authentication\UserRepository\PdoDatabaseFactory;
 
@@ -19,12 +20,22 @@ protected function setUp()
         $this->factory = new PdoDatabaseFactory();
     }
 
-    /**
-     * @expectedException Zend\Expressive\Authentication\Exception\InvalidConfigException
-     */
+    public function testInvokeWithMissingConfig()
+    {
+        // We cannot throw a ContainerExceptionInterface directly; this
+        // approach simply mimics `get()` throwing _any_ exception, which is
+        // what will happen if `config` is not defined.
+        $this->container->get('config')->willThrow(new InvalidConfigException());
+
+        $this->expectException(InvalidConfigException::class);
+        ($this->factory)($this->container->reveal());
+    }
+
     public function testInvokeWithEmptyConfig()
     {
         $this->container->get('config')->willReturn([]);
+
+        $this->expectException(InvalidConfigException::class);
         $pdoDatabase = ($this->factory)($this->container->reveal());
     }
 
@@ -48,7 +59,7 @@ public function getPdoConfig()
                 'dsn' => 'mysql:dbname=testdb;host=127.0.0.1',
                 'table' => 'test',
                 'field' => [
-                    'username' => 'email'
+                    'identity' => 'email'
                 ]
             ]]
         ];
@@ -74,7 +85,7 @@ public function testInvokeWithValidConfig()
                     'dsn' => 'sqlite:'. __DIR__ . '/../TestAssets/pdo.sqlite',
                     'table' => 'user',
                     'field' => [
-                        'username' => 'username',
+                        'identity' => 'username',
                         'password' => 'password'
                     ]
                 ]