Similar to the beforeSave() method we used in the previous chapter, Controller classes also have hook methods. They are as follows:

Both of these hooks get the $action argument, which represents the controller action being executed. This object is of little use, really, being just the container for the following:

While it's certainly interesting to know what this action really is, right now its brief description is perfectly sufficient. A close inspection of what role an action plays in route handling will be done in Chapter 12, Route Management. Most of the time, there's no need to care about the actions.

Given the definition of the beforeAction() method, it is obvious that we can restrict access to some parts of the application in the simplest possible way:

public function beforeAction($action)
{
    $parentAllowed = parent::beforeAction($action);
    $meAllowed = !Yii::$app->user->isGuest;
    return $parentAllowed and $meAllowed;
}

First we check whether the parent implementation allows the execution of the action in question. We then check whether the current user is unauthenticated by querying the isGuest property of the user component. If both these conditions are true, then we allow the execution of the action.

However, this way of blocking is not really interesting. First, it does not show the client any feedback about what really happened. Second, such a usage of beforeAction() is already anticipated in Yii 2 in the form of a special concept called filters.

Let's postpone the explanation of filters for a while and look at how we can show the client's browser what really happened with its request.

Yii employs its own handler for unhandled exceptions, which is really usable right out of the box without any further improvements. Basically, if you throw an exception of any Exception class descendant somewhere in your controller action and not handle it, Yii will show the following error message to the client:

However, here's what it will show if you throw the yiiwebNotFoundHttpException:

Note that it correctly shows the status code and the error message according to the specification of HTTP status codes. The actual status code returned will also be 404.

In fact, yiiwebNotFoundHttpException is a wrapper around the base yiiwebHttpException, which you can throw to emit arbitrary status code and message to the client, as follows:

throw new HttpException(406, 'Pretty rare error, usually you should never see it.'),

Don't forget to write use yiiwebHttpException at the beginning of your script. Here is what will be shown:

Note that the message provided in the exception constructor is shown underneath the main message of the 406 status code, which is autogenerated according to HTTP specification and is not changeable. The status code actually returned from the server will also be 406.

So, just by throwing the various kinds of HTTP exceptions you can block the user request with a descriptive message. Note, however, that nothing prevents someone from getting the following output when using yiiwebHttpException instead of its specialized subclasses:

Well, indeed anyone will think this is a server error. Even while Yii really returns status code 200, the response will be the error page. In case anyone tries to throw the HttpException with the status code 302, for example, the status code will be 302 but no redirection will happen. This is just the static page error handler in all cases.

Here is the list of all descendants of HttpException that Yii 2 defines for its users' convenience:

Another good feature of Yii exception handling is its error reporting in case the debugging mode is enabled.

Inside the index.php entry point script, before a call to require() for Yii library, the constant YII_DEBUG will be defined with the value of true:

define('YII_DEBUG', true);

If an unhandled exception like the following one is thrown in the code (this is different from the HttpException):

throw new LogicException('I am unhandled exception and I am proud of it'),

Then here's what will be shown instead of the generic "Exception" page:

This is a really amazing stacktrace page. It's so long that to fit it here we had to tear the non-unique pieces out of it. It gives several layers of code before the failed line with code highlighting, filenames, line numbers, and links to the documentation pages for the Yii classes and methods mentioned (!). It shows the server runtime configuration and also cookies sent by the client.

Okay, now here's the guard case that prevents unauthenticated users from using the controller action it is in:

if (Yii::$app->user->isGuest)
    throw new ForbiddenHttpException;

This is the simplest line of access control available for us in Yii 2. Of course, any check can be used as long as the HttpException descendant is being thrown. This is so fundamental that Yii has a special built-in AccessControl filter for it. We'll learn about the AccessControl filter later. Let's learn about what a filter is in Yii terminology.

An action filter, in short, is the beforeAction() and afterAction() methods packed into a single class, pluggable to the Controller instances through the Controller.behaviors() method.

The benefits of this approach are as follows:

For the class to become the action filter for some controller, it needs to be:

The ActionFilter itself is the special case of the behaviors that are described in Chapter 10, Events and Behaviors. For now, it's sufficient to understand that a behavior is some class containing some methods that can be declared to be an integral part of some other class, extending its feature set. If you are familiar with the concept of "traits" from PHP 5.4, this is it.

We'll not look at how to create our own ActionFilter, as it's quite unnecessary given that we already know how the beforeAction() and afterAction() methods work. Let's briefly look at the built-in Yii 2 filters instead. Detailed information about their usage can be read from their corresponding documentation pages.

As this chapter is about access control, let's look at some examples of the usage of VerbFilter and AccessControl. The AccessControl filter is so important and powerful that we'll look at it later in more detail after we explore the user roles system.

Here's how Gii protects the controller autogenerated by the VerbFilter:

    public function behaviors()
    {
        return [
            'verbs' => [
                'class' => VerbFilter::className(),
                'actions' => [
                    'delete' => ['post'],
                ],
            ],
        ];
    }

The behaviors() method must return an array of configurations for the filters to be attached to the controller. In this case, we attach the VerbFilter at the arbitrarily chosen verbs key. This VerbFilter is configured so that the delete action can be accessed only by the POST request. All other actions are unguarded, because the update form request accepts the data being POSTed and renders the HTML page for the form.

Here's how we can quite naively protect our login and logout actions using the AccessControl filter:

    public function behaviors()
    {
        return [
            'access' => [ // 1
                'class' => AccessControl::className(), // 2
                'only' => ['login', 'logout'], // 3
                'rules' => [
                    [
                        'actions' => ['login'], // 4
                        'roles' => ['?'], // 5
                        'allow' => true, // 6
                    ],
                    [
                        'actions' => ['logout'], // 7
                        'roles' => ['@'], // 8
                        'allow' => true, // 9
                    ]
                ]
            ]
        ];
    }

In the preceding code, we are using the behaviors property of our Controller to attach the yiifiltersAccessControl class to it, which will be already configured as specified.

Let's understand the preceding code line-by-line from the top to bottom:

The specific configuration parameters for each rule can be read in the documentation and/or source of the yiifiltersAccessRule class (http://www.yiiframework.com/doc-2.0/yii-filters-accessrule.html).