Rotas no CakePHP

Rotas no CakePHP: A primeira impressão de um site para um usuário — e para os motores de busca — não é o design, mas a URL. Uma URL como meusite.com.br/artigos/visualizar/1 é funcional, mas meusite.com.br/blog/como-aprender-cakephp é profissional, legível e otimizada para SEO.

Como especialista em CakePHP, preparei este décimo segundo artigo da nossa série para ensinar você a dominar o Roteamento Avançado. Vamos transformar as rotas padrão do framework em uma estrutura de URLs poderosa e personalizada, garantindo que seu projeto tenha a autoridade que ele merece.

Roteamento Avançado: Criando URLs amigáveis e personalizadas no CakePHP

Rotas no CakePHP: No CakePHP, o sistema de roteamento é o responsável por mapear uma requisição HTTP (a URL que o usuário digita) para uma ação específica dentro de um Controller. Embora o framework já venha com rotas automáticas baseadas na convenção, o verdadeiro poder surge quando assumimos o controle do arquivo config/routes.php.

Dominar o Roteamento Avançado permite que você crie slugs amigáveis, gerencie versões de APIs e proteja a estrutura interna das suas tabelas, escondendo IDs numéricos e expondo apenas termos semânticos.

1. A Anatomia de uma Rota no CakePHP

Antes de avançarmos, precisamos entender como uma rota é declarada. O roteamento no CakePHP utiliza uma sintaxe fluida que conecta um “padrão de URL” a um “destino”.

O local onde toda essa configuração acontece é o arquivo config/routes.php. Dentro do escopo de um RouteBuilder, definimos nossas regras:

PHP

use Cake\Routing\RouteBuilder;
use Cake\Routing\Route\DashedRoute;

$routes->scope('/', function (RouteBuilder $builder) {
    // Rota padrão para a Home
    $builder->connect('/', ['controller' => 'Paginas', 'action' => 'home']);
    
    // Rota personalizada
    $builder->connect('/contato', ['controller' => 'Contatos', 'action' => 'index']);
    
    $builder->fallbacks(DashedRoute::class);
});

2. Criando URLs Amigáveis (Slugs)

Para um blog como o seu, usar o ID na URL (/artigos/view/42) é péssimo para o SEO. O Google prioriza palavras-chave na URL. O objetivo é chegar em /blog/titulo-do-artigo.

Passo 1: Definindo a Rota com Parâmetros

No seu arquivo de rotas, você pode definir que qualquer coisa após /blog/ seja tratada como um parâmetro chamado slug:

PHP

$builder->connect('/blog/{slug}', 
    ['controller' => 'Artigos', 'action' => 'visualizar'],
    ['_name' => 'artigo_view'] // Nomeando a rota para facilitar o uso no HtmlHelper
)
->setPatterns(['slug' => '[a-z0-9\-]+']) // Regex para aceitar apenas letras, números e hifens
->setPass(['slug']); // Passa o parâmetro 'slug' diretamente para a função do Controller

Passo 2: Ajustando o Controller

Agora, seu Controller não busca mais pelo id, mas pelo slug:

PHP

public function visualizar($slug = null)
{
    $artigo = $this->Artigos->findBySlug($slug)->firstOrFail();
    $this->set(compact('artigo'));
}

3. Roteamento por Escopos (Scopes) e Prefixos

Se você está construindo um sistema SaaS ou um painel administrativo, você não quer que as URLs do administrador sejam misturadas com as do site público. O CakePHP resolve isso com Prefixos.

Configurando o Prefixo Admin

Imagine que você quer que todas as URLs que comecem com /admin apontem para controllers dentro de uma subpasta src/Controller/Admin/.

PHP

$builder->prefix('Admin', function (RouteBuilder $builder) {
    // Agora as rotas aqui dentro apontam para o namespace App\Controller\Admin
    $builder->connect('/', ['controller' => 'Dashboards', 'action' => 'index']);
    $builder->connect('/usuarios', ['controller' => 'Usuarios', 'action' => 'listar']);
    
    $builder->fallbacks(DashedRoute::class);
});

Isso organiza seu projeto de forma profissional:

• Site Público: src/Controller/ArtigosController.php -> /blog/meu-post
• Painel Admin: src/Controller/Admin/ArtigosController.php -> /admin/artigos

4. Passando Parâmetros Adicionais e Restrições (Regex)

O Roteamento Avançado brilha quando precisamos de precisão. Suponha que você queira criar uma URL para o arquivo do seu blog organizada por ano e mês: /arquivo/2026/04.

PHP

$builder->connect('/arquivo/{ano}/{mes}', 
    ['controller' => 'Artigos', 'action' => 'arquivo'],
    ['pass' => ['ano', 'mes']]
)
->setPatterns([
    'ano' => '[0-9]{4}', // Apenas 4 números
    'mes' => '0[1-9]|1[0-2]' // Números de 01 a 12
]);

Se o usuário digitar /arquivo/abc/99, o CakePHP nem chamará o Controller; ele retornará um erro 404 automaticamente porque a URL não condiz com o padrão definido. Isso economiza processamento e aumenta a segurança.

5. Extensões de Arquivo (JSON, XML, CSV)

Você sabia que o CakePHP pode transformar seu site em uma API apenas mudando a extensão da URL? Se você quiser que meusite.com/artigos.json retorne os dados em formato JSON, o roteamento cuida disso.

PHP

$builder->setExtensions(['json', 'xml', 'csv']);

Ao ativar isso, o framework detecta a extensão e, se você configurou o RequestHandler, ele alterna automaticamente a View para renderizar o formato solicitado. Isso é essencial para integrações com apps mobile ou exportação de dados.

6. Nomeando Rotas e o HtmlHelper

Um erro comum é “hardcodar” links nas suas Views, como <a href="/blog/meu-post">. Se amanhã você decidir mudar /blog/ para /noticias/, terá que editar todos os arquivos.

A forma profissional é usar Rotas Nomeadas:

PHP

// No routes.php
$builder->connect('/noticias/{slug}', [...], ['_name' => 'view_post']);

// No seu template (View)
echo $this->Html->link('Leia mais', [
    '_name' => 'view_post', 
    'slug' => $artigo->slug
]);

Agora, se você mudar a URL no arquivo de rotas, o link em todo o seu site mudará automaticamente. Isso é manutenibilidade.

7. Boas Práticas de Roteamento para SEO

Para que o seu blog e seus projetos ganhem tração nos buscadores, siga estas diretrizes de roteamento:

1. Use Hifens, não Underlines: meu-post é melhor que meu_post. O Google interpreta hifens como separadores de palavras.
2. Mantenha a URL Curta: Evite profundidade excessiva como /categoria/tecnologia/php/cakephp/versao5/meu-post. Prefira /blog/meu-post.
3. URLs Minúsculas: O roteamento do CakePHP diferencia maiúsculas de minúsculas por padrão no Linux. Mantenha tudo em minúsculo para evitar links quebrados.
4. Redirecionamentos 301: Se você mudou uma URL antiga, use o RedirectRoute do CakePHP para avisar os buscadores e não perder o ranqueamento.

Conclusão Rotas no CakePHP: O Mapa do seu Sucesso

Rotas no CakePHP: O Roteamento Avançado no CakePHP é o que transforma um emaranhado de scripts em uma aplicação web elegante e organizada. Quando você assume o controle das URLs, você melhora a experiência do usuário (UX), aumenta o desempenho do SEO e cria uma barreira de segurança ao ocultar a lógica interna do banco de dados.

URLs amigáveis são o cartão de visitas do seu código. Um projeto com rotas bem planejadas demonstra cuidado técnico e atenção aos detalhes, características fundamentais de um desenvolvedor especialista.

Mas antes de dominar o CakePHP, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no CakePHP, você precisará dominar as seguintes tecnologias:

E se você gosta do nosso conteúdo, não deixe de contribuir adquirindo os serviços e produtos dos nossos apoiadores e empresas que somos associados.

Agora que suas URLs estão limpas e profissionais, é hora de entender como processar as requisições que chegam por elas. No próximo artigo, veremos: “Request & Response: Manipulando dados de entrada e cabeçalhos.”

Dica de Especialista: Se as suas rotas começarem a ficar muito complexas, você pode usar o comando bin/cake routes no terminal. Ele listará todas as rotas ativas no seu sistema, mostrando exatamente qual Controller e Action cada URL está chamando. É a melhor ferramenta de debug para roteamento!