Merge branch 'develop'

Prepping for 2.2.0RC1.

src/Adapter/DbTable/AbstractAdapter.php

@@ -0,0 +1,377 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Authentication\Adapter\DbTable;
+
+
+use stdClass;
+use Zend\Authentication\Result as AuthenticationResult;
+use Zend\Authentication\Adapter\AbstractAdapter as BaseAdapter;
+use Zend\Db\Adapter\Adapter as DbAdapter;
+use Zend\Db\Sql;
+
+abstract class AbstractAdapter extends BaseAdapter
+{
+    /**
+     * Database Connection
+     *
+     * @var DbAdapter
+     */
+    protected $zendDb = null;
+
+    /**
+     * @var Sql\Select
+     */
+    protected $dbSelect = null;
+    /**
+     * $tableName - the table name to check
+     *
+     * @var string
+     */
+    protected $tableName = null;
+
+    /**
+     * $identityColumn - the column to use as the identity
+     *
+     * @var string
+     */
+    protected $identityColumn = null;
+
+    /**
+     * $credentialColumns - columns to be used as the credentials
+     *
+     * @var string
+     */
+    protected $credentialColumn = null;
+
+    /**
+     * $authenticateResultInfo
+     *
+     * @var array
+     */
+    protected $authenticateResultInfo = null;
+
+    /**
+     * $resultRow - Results of database authentication query
+     *
+     * @var array
+     */
+    protected $resultRow = null;
+
+    /**
+     * $ambiguityIdentity - Flag to indicate same Identity can be used with
+     * different credentials. Default is FALSE and need to be set to true to
+     * allow ambiguity usage.
+     *
+     * @var bool
+     */
+    protected $ambiguityIdentity = false;
+
+    /**
+     * __construct() - Sets configuration options
+     *
+     * @param DbAdapter $zendDb
+     * @param string    $tableName           Optional
+     * @param string    $identityColumn      Optional
+     * @param string    $credentialColumn    Optional
+     */
+    public function __construct(
+        DbAdapter $zendDb,
+        $tableName = null,
+        $identityColumn = null,
+        $credentialColumn = null
+    ) {
+        $this->zendDb = $zendDb;
+
+        if (null !== $tableName) {
+            $this->setTableName($tableName);
+        }
+
+        if (null !== $identityColumn) {
+            $this->setIdentityColumn($identityColumn);
+        }
+
+        if (null !== $credentialColumn) {
+            $this->setCredentialColumn($credentialColumn);
+        }
+    }
+
+    /**
+     * setTableName() - set the table name to be used in the select query
+     *
+     * @param  string $tableName
+     * @return DbTable Provides a fluent interface
+     */
+    public function setTableName($tableName)
+    {
+        $this->tableName = $tableName;
+        return $this;
+    }
+
+    /**
+     * setIdentityColumn() - set the column name to be used as the identity column
+     *
+     * @param  string $identityColumn
+     * @return DbTable Provides a fluent interface
+     */
+    public function setIdentityColumn($identityColumn)
+    {
+        $this->identityColumn = $identityColumn;
+        return $this;
+    }
+
+    /**
+     * setCredentialColumn() - set the column name to be used as the credential column
+     *
+     * @param  string $credentialColumn
+     * @return DbTable Provides a fluent interface
+     */
+    public function setCredentialColumn($credentialColumn)
+    {
+        $this->credentialColumn = $credentialColumn;
+        return $this;
+    }
+
+    /**
+     * setAmbiguityIdentity() - sets a flag for usage of identical identities
+     * with unique credentials. It accepts integers (0, 1) or boolean (true,
+     * false) parameters. Default is false.
+     *
+     * @param  int|bool $flag
+     * @return DbTable Provides a fluent interface
+     */
+    public function setAmbiguityIdentity($flag)
+    {
+        if (is_int($flag)) {
+            $this->ambiguityIdentity = (1 === $flag ? true : false);
+        } elseif (is_bool($flag)) {
+            $this->ambiguityIdentity = $flag;
+        }
+        return $this;
+    }
+
+    /**
+     * getAmbiguityIdentity() - returns TRUE for usage of multiple identical
+     * identities with different credentials, FALSE if not used.
+     *
+     * @return bool
+     */
+    public function getAmbiguityIdentity()
+    {
+        return $this->ambiguityIdentity;
+    }
+
+    /**
+     * getDbSelect() - Return the preauthentication Db Select object for userland select query modification
+     *
+     * @return Sql\Select
+     */
+    public function getDbSelect()
+    {
+        if ($this->dbSelect == null) {
+            $this->dbSelect = new Sql\Select();
+        }
+        return $this->dbSelect;
+    }
+
+    /**
+     * getResultRowObject() - Returns the result row as a stdClass object
+     *
+     * @param  string|array $returnColumns
+     * @param  string|array $omitColumns
+     * @return stdClass|bool
+     */
+    public function getResultRowObject($returnColumns = null, $omitColumns = null)
+    {
+        if (!$this->resultRow) {
+            return false;
+        }
+
+        $returnObject = new stdClass();
+
+        if (null !== $returnColumns) {
+
+            $availableColumns = array_keys($this->resultRow);
+            foreach ((array) $returnColumns as $returnColumn) {
+                if (in_array($returnColumn, $availableColumns)) {
+                    $returnObject->{$returnColumn} = $this->resultRow[$returnColumn];
+                }
+            }
+            return $returnObject;
+
+        } elseif (null !== $omitColumns) {
+
+            $omitColumns = (array) $omitColumns;
+            foreach ($this->resultRow as $resultColumn => $resultValue) {
+                if (!in_array($resultColumn, $omitColumns)) {
+                    $returnObject->{$resultColumn} = $resultValue;
+                }
+            }
+            return $returnObject;
+
+        }
+
+        foreach ($this->resultRow as $resultColumn => $resultValue) {
+            $returnObject->{$resultColumn} = $resultValue;
+        }
+        return $returnObject;
+    }
+
+    /**
+     * This method is called to attempt an authentication. Previous to this
+     * call, this adapter would have already been configured with all
+     * necessary information to successfully connect to a database table and
+     * attempt to find a record matching the provided identity.
+     *
+     * @throws Exception\RuntimeException if answering the authentication query is impossible
+     * @return AuthenticationResult
+     */
+    public function authenticate()
+    {
+        $this->authenticateSetup();
+        $dbSelect         = $this->authenticateCreateSelect();
+        $resultIdentities = $this->authenticateQuerySelect($dbSelect);
+
+        if (($authResult = $this->authenticateValidateResultSet($resultIdentities)) instanceof AuthenticationResult) {
+            return $authResult;
+        }
+
+        // At this point, ambiguity is already done. Loop, check and break on success.
+        foreach ($resultIdentities as $identity) {
+            $authResult = $this->authenticateValidateResult($identity);
+            if ($authResult->isValid()) {
+                break;
+            }
+        }
+
+        return $authResult;
+    }
+
+    /**
+     * _authenticateValidateResult() - This method attempts to validate that
+     * the record in the resultset is indeed a record that matched the
+     * identity provided to this adapter.
+     *
+     * @param  array $resultIdentity
+     * @return AuthenticationResult
+     */
+    abstract protected function authenticateValidateResult($resultIdentity);
+
+    /**
+     * _authenticateCreateSelect() - This method creates a Zend\Db\Sql\Select object that
+     * is completely configured to be queried against the database.
+     *
+     * @return Sql\Select
+     */
+    abstract protected function authenticateCreateSelect();
+
+    /**
+     * _authenticateSetup() - This method abstracts the steps involved with
+     * making sure that this adapter was indeed setup properly with all
+     * required pieces of information.
+     *
+     * @throws Exception\RuntimeException in the event that setup was not done properly
+     * @return bool
+     */
+    protected function authenticateSetup()
+    {
+        $exception = null;
+
+        if ($this->tableName == '') {
+            $exception = 'A table must be supplied for the DbTable authentication adapter.';
+        } elseif ($this->identityColumn == '') {
+            $exception = 'An identity column must be supplied for the DbTable authentication adapter.';
+        } elseif ($this->credentialColumn == '') {
+            $exception = 'A credential column must be supplied for the DbTable authentication adapter.';
+        } elseif ($this->identity == '') {
+            $exception = 'A value for the identity was not provided prior to authentication with DbTable.';
+        } elseif ($this->credential === null) {
+            $exception = 'A credential value was not provided prior to authentication with DbTable.';
+        }
+
+        if (null !== $exception) {
+            throw new Exception\RuntimeException($exception);
+        }
+
+        $this->authenticateResultInfo = array(
+            'code'     => AuthenticationResult::FAILURE,
+            'identity' => $this->identity,
+            'messages' => array()
+        );
+
+        return true;
+    }
+
+    /**
+     * _authenticateQuerySelect() - This method accepts a Zend\Db\Sql\Select object and
+     * performs a query against the database with that object.
+     *
+     * @param  Sql\Select $dbSelect
+     * @throws Exception\RuntimeException when an invalid select object is encountered
+     * @return array
+     */
+    protected function authenticateQuerySelect(Sql\Select $dbSelect)
+    {
+        $sql = new Sql\Sql($this->zendDb);
+        $statement = $sql->prepareStatementForSqlObject($dbSelect);
+        try {
+            $result = $statement->execute();
+            $resultIdentities = array();
+            // iterate result, most cross platform way
+            foreach ($result as $row) {
+                $resultIdentities[] = $row;
+            }
+        } catch (\Exception $e) {
+            throw new Exception\RuntimeException(
+                'The supplied parameters to DbTable failed to '
+                    . 'produce a valid sql statement, please check table and column names '
+                    . 'for validity.', 0, $e
+            );
+        }
+        return $resultIdentities;
+    }
+
+    /**
+     * _authenticateValidateResultSet() - This method attempts to make
+     * certain that only one record was returned in the resultset
+     *
+     * @param  array $resultIdentities
+     * @return bool|\Zend\Authentication\Result
+     */
+    protected function authenticateValidateResultSet(array $resultIdentities)
+    {
+
+        if (count($resultIdentities) < 1) {
+            $this->authenticateResultInfo['code']       = AuthenticationResult::FAILURE_IDENTITY_NOT_FOUND;
+            $this->authenticateResultInfo['messages'][] = 'A record with the supplied identity could not be found.';
+            return $this->authenticateCreateAuthResult();
+        } elseif (count($resultIdentities) > 1 && false === $this->getAmbiguityIdentity()) {
+            $this->authenticateResultInfo['code']       = AuthenticationResult::FAILURE_IDENTITY_AMBIGUOUS;
+            $this->authenticateResultInfo['messages'][] = 'More than one record matches the supplied identity.';
+            return $this->authenticateCreateAuthResult();
+        }
+
+        return true;
+    }
+
+    /**
+     * Creates a Zend\Authentication\Result object from the information that
+     * has been collected during the authenticate() attempt.
+     *
+     * @return AuthenticationResult
+     */
+    protected function authenticateCreateAuthResult()
+    {
+        return new AuthenticationResult(
+            $this->authenticateResultInfo['code'],
+            $this->authenticateResultInfo['identity'],
+            $this->authenticateResultInfo['messages']
+        );
+    }
+}