Zend_Auth_Adapter_DbTable provides the ability to authenticate against credentials stored in a
database table. Because Zend_Auth_Adapter_DbTable requires an instance of
Zend_Db_Adapter_Abstract to be passed to its constructor, each instance is bound to a
particular database connection. Other configuration options may be set through the constructor and through
instance methods, one for each option.
The available configuration options include:
tableName: This is the name of the database table that contains the authentication
credentials, and against which the database authentication query is performed.
identityColumn: This is the name of the database table column used to represent the
identity. The identity column must contain unique values, such as a username or e-mail address.
credentialColumn: This is the name of the database table column used to represent
the credential. Under a simple identity and password authentication scheme, the credential value
corresponds to the password. See also the credentialTreatment option.
credentialTreatment: In many cases, passwords and other sensitive data are
encrypted, hashed, encoded, obscured, or otherwise treated through some function or algorithm.
By specifying a parameterized treatment string with this method, such as 'MD5(?)'
or 'PASSWORD(?)', a developer may apply such arbitrary SQL upon input credential
data. Since these functions are specific to the underlying RDBMS, check the database manual for
the availability of such functions for your database system.
Example 3.3. Basic Usage
As explained in the introduction, the Zend_Auth_Adapter_DbTable constructor requires an
instance of Zend_Db_Adapter_Abstract that serves as the database connection to which the
authentication adapter instance is bound. First, the database connection should be created.
The following code creates an adapter for an in-memory database, creates a simple table schema, and inserts a row against which we can perform an authentication query later. This example requires the PDO SQLite extension to be available:
<?php
// Create an in-memory SQLite database connection
require_once 'Zend/Db/Adapter/Pdo/Sqlite.php';
$dbAdapter = new Zend_Db_Adapter_Pdo_Sqlite(array('dbname' => ':memory:'));
// Build a simple table creation query
$sqlCreate = 'CREATE TABLE [users] ( '
. '[id] INTEGER NOT NULL PRIMARY KEY, '
. '[username] VARCHAR(50) UNIQUE NOT NULL, '
. '[password] VARCHAR(32) NULL, '
. '[real_name] VARCHAR(150) NULL)';
// Create the authentication credentials table
$dbAdapter->query($sqlCreate);
// Build a query to insert a row for which authentication may succeed
$sqlInsert = 'INSERT INTO users (username, password, real_name) '
. 'VALUES ("my_username", "my_password", "My Real Name")';
// Insert the data
$dbAdapter->query($sqlInsert);
With the database connection and table data available, an instance of
Zend_Auth_Adapter_DbTable may be created. Configuration option values may be passed to the
constructor or deferred as parameters to setter methods after instantiation:
<?php
require_once 'Zend/Auth/Adapter/DbTable.php';
// Configure the instance with constructor parameters...
$authAdapter = new Zend_Auth_Adapter_DbTable($dbAdapter, 'users', 'username', 'password');
// ...or configure the instance with setter methods
$authAdapter = new Zend_Auth_Adapter_DbTable($dbAdapter);
$authAdapter->setTableName('users')
->setIdentityColumn('username')
->setCredentialColumn('password');
At this point, the authentication adapter instance is ready to accept authentication queries. In order
to formulate an authentication query, the input credential values are passed to the adapter prior to
calling the authenticate() method:
<?php
// Set the input credential values (e.g., from a login form)
$authAdapter->setIdentity('my_username')
->setCredential('my_password');
// Perform the authentication query, saving the result
$result = $authAdapter->authenticate();
In addition to the availability of the getIdentity() method upon the authentication result object, Zend_Auth_Adapter_DbTable also supports retrieving the table row upon authentication success:
<?php
// Print the identity
echo $result->getIdentity() . "\n\n";
// Print the result row
print_r($identity);
/* Output:
my_username
Array
(
[id] => 1
[username] => my_username
[password] => my_password
[real_name] => My Real Name
)
*/
Since the table row contains the credential value, it is important to secure the values against unintended access.
By default, Zend_Auth_Adapter_DbTable returns the identity supplied back to the auth object upon successful authentication. Another use case scenario, where developers want to store to the persistent storage mechanism of Zend_Auth an identity object containing other useful information, is solved by using the getResultRowObject() method to return a stdClass object. The following code snippet illustrates its use:
<?php
// authenticate with Zend_Auth_Adapter_DbTable
$result = $this->_auth->authenticate($adapter);
if ($result->isValid()) {
// store the identity as an object where only the username and real_name have been returned
$this->_auth->getStorage()->write($adapter->getResultRowObject(array('username', 'real_name'));
// store the identity as an object where the password column has been omitted
$this->_auth->getStorage()->write($adapter->getResultRowObject(null, 'password'));
/* ... */
} else {
/* ... */
}