Dica Rápida: Migrando Aplicação CakePHP 3.x para 4.x

Embora tenha havido um grande esforço em manter o máximo de compatibilidade entre as duas recentes versões do framework, ao migrar uma aplicação de complexidade razoável encontrei várias dificuldades não tão bem documentadas.

Pra me poupar passar por esses problemas no futuro, e talvez te poupar de dor de cabeça também, aqui vai um resumo do que observar:

• Rotas e links: revisite todas as suas rotas e criação de links/redirects. Nomes de prefixos, plugins e controladores devem ser escritos como são, sem alteração para caixa baixa (lowercase) e underscore. O que antes seria my_products agora deve ser MyProducts, como no nome da classe MyProductsController. No caso dos links, se antes ao usar o UrlHelper não havia problema de uma rota não ter sido mapeada, agora você terá uma exceção.
• Plugins: não defina ou carregue suas rotas no bootstrap.php do plugin, isso fará com que a aplicação tenha qualquer outra rota ignorada.
• Mocks: com a nova versão, veio também o uso do phpunit 8.5, que por sua vez, introduz algumas quebras de compatibilidade. Isso afeta em especial a criação de mocks em modelos ligados a behaviors (se você tentar usar o mock em um método do behavior). No pull-request que abri para o futuro CakePHP 4.1, é resolvida o problema de warnings gerados, porém, em alguns testes meus, é obrigatório incluir algum método concreto da Table/Model que está sendo mockada junto com o método de behavior na lista de métodos no mock – caso contrário, o warning volta a aparecer (esse problema acontecia por uma falha no pull-request que criei, mas fiz um segundo com uma implementação melhor e não há mais necessidade disso).
• Tests: se em algum teste você faz um $this->loadPlugin('MyPlugin'); no seu setUp(), se esse plugin possuir rotas, as rotas da sua aplicação não serão carregadas. Houve uma mudança na verificação de inicialização das rotas e necessidade de carregamento – antes, havia uma variável de controle que só era definida após carregar as rotas da aplicação, agora, só é checado se já existe alguma rota declarada, e se houver, supõe-se que todo procedimento já foi realizado com sucesso.

Destes problemas, o mais trabalhoso de corrigir é o com as rotas/links – os outros três a dificuldade foi realmente entender o que estava acontecendo.