DeitAuthenticationModule
DeitAuthenticationModule is a pre-built authentication module for Zend Framework v2. It provides log-in and log-out functionality with a high degree of flexibility. To restrict access to routes, controller actions or other resources, also check out our DeitAuthorisationModule module., (*1)
For a full featured authentication module see ZfcUser., (*2)
Installation
With Composer
Add "digitaledgeit/zf2-authentication-module": "master-dev"
to the require
section of your composer.json file and then run composer update
., (*3)
Without Composer
Download the repo archive, create a new directory named %app%/module/DeitAuthenticationModule
and extract the contents of the archive., (*4)
Configuration
Configure application.config.php
to load the module:, (*5)
'modules' => array(
'DeitAuthenticationModule',
'Application',
),
Configure an authentication adapter that implements \Zend\Authentication\Adapter\AdapterInterface., (*6)
'service_manager' => array(
'factories' => array(
'deit_authentication_adapter' => function($sm) {
//create an adapter
//for example: http://framework.zend.com/manual/2.0/en/modules/zend.authentication.adapter.dbtable.html
//for example: https://github.com/doctrine/DoctrineModule/blob/master/docs/authentication.md
},
),
),
Getting the authenticated identity
The module provides a controller plugin and a view helper for fetching the identity., (*7)
$this->identity();
When adapters like \Zend\Authentication\Adapter\DbTable
or \DoctrineModule\Authentication\Adapter\ObjectRepository
retrieve a database entity and store it as the identity in the session, then you often run into problems with the identity data stored in the session being out-of-date after the identity has been updated in the database (e.g. if they've updated their name and you use the identity
view helper to fetch the user's name in the layout then the updated name won't display until next time the user logs in)., (*8)
To circumvent this issue you may specify a callback to fetch the entity on each page request so its always up-to-date., (*9)
'deit_authentication' => array(
'fetch_entity_from_identity_callback' => function($identity, \Zend\ServiceManager\ServiceLocatorInterface $sm) {
//fetch and return your entity
//for example: fetch a user based on the user's Facebook ID returned by the adapter
return $em->findOneById($identity['facebook_id');
}
),
Using a custom view
The default view is very basic and just displays the heading "Log in" and uses the form view helper to render the form. Changing the view to your own is simple. Just override the template mapping like so:, (*10)
'view_manager' => array(
'template_map' => array(
'deit-authentication-module/log-in' => __DIR__.'/../view/your-view-path/log-in.phtml',
),
),
The view is passed two variables, a `$form` and a feedback `$message`. When an error occurs the `$message` may contain a message similar to "invalid credentials, please try again".
Override the deit_authentication_form
key in the service manager to provide your own form. Forms must implement \DeitAuthenticationModule\Form\AuthenticationInterface
or extend \DeitAuthenticationModule\Form\AbstractAuthentication
., (*11)
'service_manager' => array(
'factories' => array(
'deit_authentication_form' => function($sm) {
return new \Application\Form\MyAuthenticationForm();
},
},
},
By default the form is validated on POST but this behaviour can be overridden by implementing the isSubmitted($request)
method., (*12)
class MyForm extends \DeitAuthenticationModule\Form\AbstractAuthentication {
public function isSubmitted(\Zend\Http\Request $request) {
return $request->isGet() && $request->getQuery('identity') && $request->getQuery('credential');
}
}
If your form doesn't provide an identity or credential field you can specify a callback to map the user submitted data to your adapter., (*13)
'deit_authentication' => array(
'map_auth_data_to_adapter_callback' => function(array $data, \Zend\Authentication\Adapter\AdapterInterface $adapter) {
//in this example the adapter has a single parameter (not identity and credential like the ones provided by Zend).
//this will be useful for alternate log-in schemes like Facebook OAuth
if (isset($data['code'])) {
$adapter->setCode($data['code']);
}
},
),
Listening for events
The authentication controller triggers two events, log-in
and log-out
. The module provides its own \Zend\EventManager\EventManager
and can be retrieved from the service manager using the deit_authentication_events
key., (*14)
class Module {
public function onBootstrap(MvcEvent $event) {
$sm = $event->getApplication()->getServiceManager();
$em = $sm->get('deit_authentication_events');
$em->attach('log-in', function($event /** @var \DeitAuthenticationModule\Event\Authenticate $event */) {
if ($event->getResult()->isValid()) {
//handle the event here
}
});
$em->attach('log-out', function($event) {
/**
* @var mixed $oldIdentity
*/
$oldIdentity = $event->getParam('identity');
//handle the event here
});
}
}