How to create an authentication middleware to validate tokens in Phalcon?

[Jose12Abel]

Hello community,

I'm developing a REST API using the Phalcon framework (version X.X) and need to implement a security layer to protect my endpoints.

My goal:

I want the request to be intercepted before any action logic is executed in my controllers to validate an authentication token (e.g., a JWT) sent in the headers (Authorization: Bearer ).

If the token is valid, the request should continue to the requested endpoint. If the token is invalid, nonexistent, or has expired, the system should stop execution and return an error response (e.g., a 401 Unauthorized) automatically, without the controller code having to perform this validation.

What I've researched:

I've read that this can be achieved in Phalcon in several ways, but I'm not sure which is the "best practice" or the most efficient and maintainable. My ideas are:

1. Use the EventsManager: Listen to the dispatcher:beforeExecuteRoute event to execute my token validation logic before the route is dispatched to the controller.
2. Create Middleware: I understand that newer versions of Phalcon have a middleware system similar to other frameworks.
3. Do it in a Base Controller: Create a BaseController and put the validation logic in its initialize() method. However, this would force me to always inherit from this controller, and it doesn't seem that decoupled.

My question is:

What is the recommended and most robust way to implement this global authentication filter in Phalcon? Is it through the EventsManager or by creating a Middleware class?

It would be very helpful if you could provide a basic example of how to structure this code. For example:

• Where should I register the validation service in the Dependency Injection (DI) container?
• How do I access the request object within the event handler or middleware to read the headers?
• How do I stop execution and send a JSON error response from that point?

I want to avoid having to add this to every action:

<?php

class UsersController extends ControllerBase
{
    public function getAction($id)
    {
        // NO QUIERO HACER ESTO MANUALMENTE AQUÍ
        $token = $this->request->getHeader('Authorization');
        if (!$this->authManager->validate($token)) {
            $this->response->setStatusCode(401, 'Unauthorized');
            $this->response->setJsonContent(['error' => 'Token inválido']);
            return $this->response;
        }
        
        // Lógica del endpoint...
    }
}

[niden]

Have a look at this repository: https://github.com/phalcon/rest-api

[niden]

It uses option 2, middleware