Like Zend's ErrorHandler plugin, the default is ErrorController::errorAction() in the default module. We made the request variables the plugin makes available to that action identical to those set up by ErrorHandler to provide reuse. You can change the forward location if you desire.

<?php
$module = 'default';
$controller = 'index';
$action = 'error';
/* @var $plugin Xyster_Controller_Plugin_Acl */
$plugin->setAccessDenied($module, $controller, $action);

The plugin registers a preDispatch hook to verify access. If the authenticated user isn't allowed to access the action about to be dispatched, the plugin forwards them to the error location specified.

If an action is denied but the user isn't authenticated (meaning Zend_Auth doesn't have an identity), the plugin will forward them to a location where they should be prompted for credentials. By default, this is the 'index' action of the 'login' controller in the default module. This can be changed by using the setLogin method.

<?php
$module = 'default';
$controller = 'index';
$action = 'login';
/* @var $plugin Xyster_Controller_Plugin_Acl */
$plugin->setLogin($module, $controller, $action);

The login action should process the the user-supplied credentials and authenticate the user.

You can set up the access control rules using the allow, deny, and setRules methods on the plugin. The rules must be defined before the Front Controller dispatches the request. Remember that the role used in the rule must be defined in the ACL before you can add the rule. The following example allows the authenticated user access to all actions in the 'foo' controller of the 'default' module.

<?php
$acl = new Zend_Acl;
$identity = Zend_Auth::getInstance()->getIdentity();
$acl->addRole(new Zend_Acl_Role($identity);
$plugin = new Xyster_Controller_Plugin_Acl($acl);
$plugin->allow($identity, 'default', 'foo');
$front = Zend_Controller_Front::getInstance();
$front->registerPlugin($plugin);

You can add as many rules as you want using the fluent interface of the allow method.

<?php
$plugin->allow('admin', null) // admin can access everything
	->allow('moderators', 'forum', 'mod') // moderators can access the 'mod' controller
	->allow(null, 'forum', 'view') // all users can access the 'view' controller
	->deny('trolls'); // all forum trolls should be forbidden

You can also add multiple rules at once by passing an array to the setRules method. Each element in the array must be an array with several keys.

If 'type' is omitted or is null, Zend_Acl::TYPE_ALLOW is assumed. If any of the other keys are omitted, null is assumed.

<?php
$rules = array(
    array('role'=>'admin'),
    array('role'=>'moderators', 'module'=>'forum', 'controller'=>'mod'), 
    array('module'=>'forum', 'controller'=>'view'),
    array('type'=>Zend_Acl::TYPE_DENY, 'role'=>'trolls')
);
/* @var $plugin Xyster_Controller_Plugin_Acl */
$plugin->setRules($rules);

<?php
$adapter = new MyAuthAdapter;
$plugin = new Xyster_Controller_Plugin_Auth;
$plugin->setAuthAdapter($adapter);

<?php
public function loginAction()
{
	if ( $this->getRequest()->isPost() ) {
		$username = $this->_getParam('username');
		$password = $this->_getParam('password');
		$adapter = new MyAuthAdapter($username, $password);
		$plugin = $this->getFrontController()->getPlugin('Xyster_Controller_Plugin_Auth');
		$plugin->setAuthAdapter($adapter);
		return;
	} else {
		// show login form
	}
}

At the routeStartup event or when given an adapter, the plugin will try to authenticate the user if an identity has not been stored. If the authentication fails, the user will be forwarded to a login failure action. By default, this is the 'index' action of the 'login' controller in the default module. You can change this using the setFailure method.

<?php
$module = 'default';
$controller = 'index';
$action = 'login';
/* @var $plugin Xyster_Controller_Plugin_Auth */
$plugin->setFailure($module, $controller, $action);

A Zend_Auth_Result object will be passed to this action as the result parameter.

If the authentication succeeds, the user will be forwarded to a login success action. By default, this is the 'success' action of the 'login' controller in the default module. You can change this using the setSuccess method.

<?php
$module = 'default';
$controller = 'index';
$action = 'myAccount';
/* @var $plugin Xyster_Controller_Plugin_Auth */
$plugin->setSuccess($module, $controller, $action);

Once the user is authenticated, the plugin will then retrieve and store a role that represents the authenticated user. By default, Xyster_Acl_Role_Provider will be used, but you can define your own provider using the setRoleProvider method. If an ACL object is supplied, the plugin will take the role it got from the provider and add it to the ACL.

<?php
$acl = new Zend_Acl;
$authAdapter = new MyAuthAdapter();
$plugin = new Xyster_Controller_Plugin_Auth($authAdapter, $acl);
$front = Zend_Controller_Front::getInstance();
$front->registerPlugin($plugin);

Once authentication takes place, the role generated for the current user is available from the getRole method.