Middleware vs Dispatcher Filter Execution Order in CakePHP 4.x/5.x

In CakePHP 4.x and 5.x, the execution order of PSR-15 middleware and legacy dispatcher filters is reversed compared to version 3.x. In the older architecture, filters were central to the request lifecycle, but in modern versions, the middleware stack executes first. Legacy dispatcher filters—wrapped by the compatibility layer—execute later, during the Controller lifecycle.

This reversal is significant because middleware operates on an 'onion' model, where the request passes through each layer and the response passes back out before the Controller is even instantiated. If your application relies on filters to mutate headers or modify request state, those changes may occur too late to affect middleware or may overwrite an already generated response.

Key Execution Differences

• PSR-15 Middleware: Executes early. It is ideal for global concerns like CORS, authentication, and early request parsing.
• Dispatcher Filters (Legacy): Execute after the middleware stack. They are tied to Controller events like beforeFilter and beforeRender.

Is the altered order acceptable?

Whether this is acceptable depends on the specific dependency of your plugin's logic:

• CORS/Auth Headers: If a legacy filter adds headers that a CORS middleware needs to validate, the middleware will fail or produce an incorrect response. These must be moved to middleware.
• State Mutation: If a filter modifies a request attribute that a middleware uses for routing, the middleware will not see that change.
• Event Timing: Events like beforeRender and beforeRedirect are inherently Controller-centric. You cannot easily 'shift' these to run before middleware without rewriting the logic into PSR-15 middleware.

Recommended Migration Strategy

To ensure long-term maintenance and prevent silent regressions, follow this scoped approach:

1. Identify Critical Filters: Locate filters that handle global logic (Security, Headers, Routing, Logging).
2. Rewrite as Middleware: Convert these into PSR-15 middleware classes. This ensures they run at the start of the cycle.
3. Retain Controller-Specific Filters: Keep dispatcher filters only for logic that strictly requires access to the Controller instance or specific view variables (e.g., complex view-formatting).
4. Verification: Use a simple debug log in both the middleware process method and the filter beforeFilter to verify the sequence in your specific environment.

To provide a more specific recommendation, are your filters primarily modifying the Response headers or are they altering the Request data for routing logic?